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

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

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"
    }
}