Reserve Payments

A Reserved payment is similar to a regular payment with two major differences:
A Reserved Payment has to be captured
A Reserved Payment can be cancelled
If you'd like to reserve a payment for a Product, define the attribute reserved_price for that product and the BuiltOn API will create a Reserved Payment when that product is placed in an Order. The payment created for that order will have amount_reserved attribute set based on the reserved_price for all products in the Order.
In the customer's bank, the money will be put in a 'reserved' status, but not be withdrawn until the payment is complete.
A Reserved Payment has been created with a Stripe Payment Method will be automatically cancelled by Stripe after 7 days if it is not confirmed (captured).
Capture a Payment
Parameters
HTTP - Stripe
Arguments
Type
Description
reserved_price
float
The amount you want to capture. If it's not defined, then the payment will be charged normally.
1
Request --
2
​
3
POST /payments/<payment_id>/pay HTTP/1.1
4
Content-Type: application/json
5
Authorization: Bearer <admin-jwt> or <Service-Account-key>
6
X-Builton-Api-Key: <builton-api-key>
7
Host: api.builton.dev
8
​
9
{
10
    "amount_to_capture": 240.0
11
}
Copied!
1
Response --
2
HTTP/1.1 200 OK
3
Content-Type: application/json
4
​
5
{
6
    "_id": {
7
        "$oid": <payment_id>
8
    },
9
    "active": true,
10
    "amount": 240.0,
11
    "amount_paid": 240.0,
12
    "amount_refunded": 0.0,
13
    "amount_reserved": 240.0,
14
    "company": {
15
        "$oid": "5ce68495873a43000d3a0d1c"
16
    },
17
    "created": {
18
        "$date": 1584019536292
19
    },
20
    "currency": "EUR",
21
    "current_state": "succeeded",
22
    "deleted": false,
23
    "description": "",
24
    "human_id": "ZZQWEY",
25
    "is_reserved": true,
26
    "metadata": {
27
        "charge_id": "ch_1GLr2aJzwMQnQo9JfHRXHZRP",
28
        "intent_id": "pi_1GLr2aJzwMQnQo9JaecBib5W"
29
    },
30
    "modified": {
31
        "$date": 1584019549112
32
    },
33
    "payment_date": {
34
        "$date": 1584019536289
35
    },
36
    "payment_method": {
37
        "$oid": "5e563483049e4300087d82a1"
38
    },
39
    "refunds": [],
40
    "subject": {
41
        "_cls": "Order",
42
        "_ref": "5e67a4d2c7a4b1000829241e"
43
    },
44
    "user": {
45
        "$oid": "57ee9c72d76d431f85111432"
46
    }
47
}
Copied!
Cancel a Payment
A payment can be cancelled only if the current_state is one of these states: created, pending, reserved.
Parameters
HTTP - Stripe
Arguments
Type
Description
reason
string
Must be one of the following: duplicate, fraudulent, requested_by_customer and abandoned.
1
Request --
2
​
3
POST /payments/<payment_id>/cancel HTTP/1.1
4
Content-Type: application/json
5
Authorization: Bearer <admin-jwt> or <Service-Account-key>
6
X-Builton-Api-Key: <builton-api-key>
7
Host: api.builton.dev
8
​
9
{
10
    "reason": "duplicate"
11
}
Copied!
1
Response --
2
HTTP/1.1 200 OK
3
Content-Type: application/json
4
​
5
{
6
    "_id": {
7
        "$oid": <payment_id>
8
    },
9
    "active": true,
10
    "amount": 240.0,
11
    "amount_refunded": 0.0,
12
    "amount_reserved": 240.0,
13
    "company": {
14
        "$oid": "5ce68495873a43000d3a0d1c"
15
    },
16
    "created": {
17
        "$date": 1584001298313
18
    },
19
    "currency": "EUR",
20
    "current_state": "cancelled",
21
    "deleted": false,
22
    "description": "",
23
    "human_id": "WR4VPE",
24
    "is_reserved": true,
25
    "metadata": {
26
        "charge_id": "ch_1GLr2aJzwMQnQo9JfHRXHZRP",
27
        "intent_id": "pi_1GLr2aJzwMQnQo9JaecBib5W"
28
    },
29
    "modified": {
30
        "$date": 1584001701083
31
    },
32
    "payment_date": {
33
        "$date": 1584001298309
34
    },
35
    "payment_method": {
36
        "$oid": "5e563483049e4300087d82a1"
37
    },
38
    "refunds": [],
39
    "subject": {
40
        "_cls": "Order",
41
        "_ref": "5e67a4d2c7a4b1000829241e"
42
    },
43
    "user": {
44
        "$oid": "5e562c93839ed100081626dc"
45
    }
46
}
Copied!

Strong Customer Authentication

Refunding

Last modified 1yr ago

Copy link

Contents

Capture a Payment

Cancel a Payment