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
Parameters

Arguments

Type

Description

reserved_price

float

The amount you want to capture. If it's not defined, then the payment will be charged normally.

HTTP - Stripe
Request --
POST /payments/<payment_id>/pay HTTP/1.1
Content-Type: application/json
Authorization: Bearer <admin-jwt> or <Service-Account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"amount_to_capture": 240.0
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {
"$oid": <payment_id>
},
"active": true,
"amount": 240.0,
"amount_paid": 240.0,
"amount_refunded": 0.0,
"amount_reserved": 240.0,
"company": {
"$oid": "5ce68495873a43000d3a0d1c"
},
"created": {
"$date": 1584019536292
},
"currency": "EUR",
"current_state": "succeeded",
"deleted": false,
"description": "",
"human_id": "ZZQWEY",
"is_reserved": true,
"metadata": {
"charge_id": "ch_1GLr2aJzwMQnQo9JfHRXHZRP",
"intent_id": "pi_1GLr2aJzwMQnQo9JaecBib5W"
},
"modified": {
"$date": 1584019549112
},
"payment_date": {
"$date": 1584019536289
},
"payment_method": {
"$oid": "5e563483049e4300087d82a1"
},
"refunds": [],
"subject": {
"_cls": "Order",
"_ref": "5e67a4d2c7a4b1000829241e"
},
"user": {
"$oid": "57ee9c72d76d431f85111432"
}
}

Cancel a Payment

A payment can be cancelled only if the current_state is one of these states: created, pending, reserved.

Parameters
HTTP - Stripe
Parameters

Arguments

Type

Description

reason

string

Must be one of the following: duplicate, fraudulent, requested_by_customer and abandoned.

HTTP - Stripe
Request --
POST /payments/<payment_id>/cancel HTTP/1.1
Content-Type: application/json
Authorization: Bearer <admin-jwt> or <Service-Account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"reason": "duplicate"
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {
"$oid": <payment_id>
},
"active": true,
"amount": 240.0,
"amount_refunded": 0.0,
"amount_reserved": 240.0,
"company": {
"$oid": "5ce68495873a43000d3a0d1c"
},
"created": {
"$date": 1584001298313
},
"currency": "EUR",
"current_state": "cancelled",
"deleted": false,
"description": "",
"human_id": "WR4VPE",
"is_reserved": true,
"metadata": {
"charge_id": "ch_1GLr2aJzwMQnQo9JfHRXHZRP",
"intent_id": "pi_1GLr2aJzwMQnQo9JaecBib5W"
},
"modified": {
"$date": 1584001701083
},
"payment_date": {
"$date": 1584001298309
},
"payment_method": {
"$oid": "5e563483049e4300087d82a1"
},
"refunds": [],
"subject": {
"_cls": "Order",
"_ref": "5e67a4d2c7a4b1000829241e"
},
"user": {
"$oid": "5e562c93839ed100081626dc"
}
}