Search…
Reserve Payments
You can capture a payment amount from a user before you charge them, ensuring they have the amount needed before they use your product.
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!