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
HTTP
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
1
Request --
2
​
3
POST https://api.builton.dev/payments/<payment_id>/refund HTTP/1.1
4
Content-Type: application/json
5
Authorization: Bearer <service-account-key>
6
X-Builton-Api-Key: <builton-api-key>
7
Host: api.builton.dev
Copied!
1
Response --
2
​
3
HTTP/1.1 200 OK
4
Content-Type: application/json
5
​
6
{
7
   "_id": {
8
      "$oid": "5de77493eec87269d95c85ac"
9
   },
10
   "active": true,
11
   "amount": 42.42,
12
   "amount_refunded": 42.42,
13
   "company": {
14
      "$oid": "5de77493eec87269d95c85a9"
15
   },
16
   "created": {
17
      "$date": 1575449747940
18
   },
19
   "currency": "NOK",
20
   "current_state": "refunded",
21
   "deleted": false,
22
   "description": "",
23
   "human_id": "2DXDE6",
24
   "metadata": {
25
      [...]
26
   },
27
   "modified": {
28
      "$date": 1575449748244
29
   },
30
   "payment_date": {
31
      "$date": 1575449747993
32
   },
33
   "payment_method": {
34
      "$oid": "5de77493eec87269d95c85ab"
35
   },
36
   "refunds": [
37
      {
38
         "_id": "re_1FZIKEEeeXxFpLJthDySZrHY",
39
         "amount": 42.42,
40
         "charge_id": "ch_1FZIKDEeeXxFpLJtUmu0TSCG",
41
         "created": {
42
            "$date": 1575449748231
43
         },
44
         "properties": {
45
            "reason": "requested_by_customer"
46
         },
47
         "status": "succeeded"
48
      }
49
   ],
50
   "user": {
51
      "$oid": "5de77493eec87269d95c85aa"
52
   }
53
}
Copied!
It is only callable by an admin user or a service account key.

Reserve Payments

Next - Building Blocks

Webhooks

Last modified 2yr ago

Copy link

Contents

Refund Object

Refund a Payment