Refunding

Vipps and Stripe support the ability to refund charges, either fully or partially. Once issued, a refund cannot be canceled. You can issue multiple refunds for one payment, but you cannot refund a total greater than the original amount.

Refund Object

Attributes

Type

Description

amount

float

The Refund's amount. The amount can be lower or equal to the Payment amount, but not higher.

charge_id

string

The reference of the Payment Provider transaction. E.g: For a Stripe payment it will be the Stripe charge_id. For a Vipps payment it will be the Vipps order_id.

properties

object

Details depend on the Payment Provider.

The propertieswill have the following key and value by default:

• reason => duplicate, fraudulentor,requested_by_customer

Refund a Payment

A Payment can be fully or partially refunded and its current_state will change to refunded or, partial_refund.

When a refund process is triggered, on success the Payment current_state changes to pending_refundor refund_failed.

A payment can be refunded multiple times but the total refunded amount can't be higher than the initial Payment amount.

Example:

Let's assume that you have a Payment for 250 NOK.

First, you refund half the initial amount: 125. If the refund is successful, the payment current_status changes to partial_refund and amount_refundedwill be 125.

Then later, you decide to refund it with the amount set to 125. The Payment amount_refundedwill be 250 and the current_status will be refunded.

Parameters

Attributes	Type	Description
amount	float	The amount of the refund. The amount can not be bigger than the Payment amount.
reason	string	The reason can only be: duplicate, fraudulentor requested_by_customer

HTTP

Request --

POST https://api.builton.dev/payments/<payment_id>/refund HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

Response --

HTTP/1.1 200 OK
Content-Type: application/json

{
   "_id": {
      "$oid": "5de77493eec87269d95c85ac"
   },
   "active": true,
   "amount": 42.42,
   "amount_refunded": 42.42,
   "company": {
      "$oid": "5de77493eec87269d95c85a9"
   },
   "created": {
      "$date": 1575449747940
   },
   "currency": "NOK",
   "current_state": "refunded",
   "deleted": false,
   "description": "",
   "human_id": "2DXDE6",
   "metadata": {
      [...]
   },
   "modified": {
      "$date": 1575449748244
   },
   "payment_date": {
      "$date": 1575449747993
   },
   "payment_method": {
      "$oid": "5de77493eec87269d95c85ab"
   },
   "refunds": [
      {
         "_id": "re_1FZIKEEeeXxFpLJthDySZrHY",
         "amount": 42.42,
         "charge_id": "ch_1FZIKDEeeXxFpLJtUmu0TSCG",
         "created": {
            "$date": 1575449748231
         },
         "properties": {
            "reason": "requested_by_customer"
         },
         "status": "succeeded"
      }
   ],
   "user": {
      "$oid": "5de77493eec87269d95c85aa"
   }
}

It is only callable by an admin user or a service account key.