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).
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. |
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"
}
}
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. |
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"
}
}
Last modified 2yr ago