Authorize a payment

Last updated: April 29, 2022

The Unified Payments API is able to process a number of different authorization types:

Final: indicates to the schemes that the amount being authorized will not change.
Estimated: indicates to the schemes that the amount being authorized is an estimate.
Incremental: follows an estimated authorization and either increases the authorization amount for the payment or, for Mastercard only, extends the authorization validity period.

When requesting a payment in the Unified Payments API, you can specify whether you want the authorization to be final or estimated using the authorization_type field. If omitted, the authorization will be requested as final.

Information

If the authorization type is estimated, we will automatically disable auto capture for the payment.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "card",
4    "number": "4242424242424242",
5    "expiry_month": 12,
6    "expiry_year": 2025
7  },
8  "amount": 100,
9  "currency": "USD",
10  "reference": "ORD-752-814",
11  "authorization_type": "Estimated",
12  "processing_channel_id": "mer_q4dbxom5jbgudnjzjpz7j2z6uq",
13  "capture": false
14}

Use the approved field to check whether or not the authorization was successful ("approved": true). The balances object provides an overview of the payment’s balances, which helps you determine the amount that can be used for each subsequent action on the payment.


1{
2  "id": "pay_tqgk5c6k2nnexagtcuom5ktlua",
3  "action_id": "act_tqgk5c6k2nnexagtcuom5ktlua",
4  "amount": 100,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "503198",
9  "expires_on": "2020-04-05T10:11:12Z",
10  "eci": "05",
11  "scheme_id": "511129554406717",
12  "response_code": "10000",
13  "response_summary": "Approved",
14  "balances": {
15    "total_authorized": 100,
16    "total_voided": 0,
17    "available_to_void": 100,
18    "total_captured": 0,
19    "available_to_capture": 100,
20    "total_refunded": 0,
21    "available_to_refund": 0
22  },
23  "risk": {
24    "flagged": false
25  },
26  "source": {
27    "id": "src_il5ncjpijceulefzbhkm2c3di4",
28    "type": "card",
29    "expiry_month": 12,
30    "expiry_year": 2025,
31    "scheme": "Visa",
32    "last4": "4242",
33    "fingerprint": "71580B426F1D190D29087FF265D8F48DF1AD34EDE41C27CBFF9D23C1A14D1776",
34    "bin": "424242",
35    "card_type": "CREDIT",
36    "card_category": "CONSUMER",
37    "issuer": "Test Bank",
38    "issuer_country": "US",
39    "product_id": "A",
40    "product_type": "Visa Traditional",
41    "avs_check": "S",
42    "cvv_check": "Y",
43    "payouts": true,
44    "fast_funds": "d"
45  },
46  "customer": {
47    "id": "cus_sozpnpktte5uzooigxau35uloq"
48  },
49  "processed_on": "2020-03-16T22:11:24Z",
50  "reference": "ORD-752-814",
51  "processing": {
52    "acquirer_transaction_id": "8367314942",
53    "retrieval_reference_number": "162588399162"
54  },
55  "_links": {
56    "self": {
57      "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua"
58    },
59    "actions": {
60      "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/actions"
61    },
62    "authorize": {
63      "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/authorizations"
64    },
65    "capture": {
66      "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/captures"
67    },
68    "void": {
69      "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/voids"
70    }
71  }
72}

If a payment was requested with an estimated authorization, you can increase the authorization amount for that payment by submitting incremental authorizations, or extend the authorization validity period (Mastercard only).

Use the details below to set up your request.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments/{id}/authorizations


1{
2  "amount": 50,
3  "reference": "ORD-752-814"
4}


1{
2  "action_id": "act_q4dbxom5jbgudnjzjpz7j2z6uq",
3  "amount": 50,
4  "currency": "USD",
5  "approved": true,
6  "status": "Authorized",
7  "auth_code": "503198",
8  "expires_on": "2020-04-20T10:11:12Z",
9  "eci": "05",
10  "scheme_id": "511129554406717",
11  "response_code": "10000",
12  "response_summary": "Approved",
13  "balances": {
14    "total_authorized": 150,
15    "total_voided": 0,
16    "available_to_void": 150,
17    "total_captured": 0,
18    "available_to_capture": 150,
19    "total_refunded": 0,
20    "available_to_refund": 0
21  },
22  "processed_on": "2020-03-16T22:11:24Z",
23  "reference": "ORD-752-814",
24  "processing": {
25    "acquirer_transaction_id": "8367314942",
26    "retrieval_reference_number": "162588399162"
27  },
28  "_links": {
29    "self": {
30      "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua"
31    },
32    "actions": {
33      "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/actions"
34    },
35    "authorize": {
36      "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/authorizations"
37    },
38    "capture": {
39      "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/captures"
40    },
41    "void": {
42      "href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/voids"
43    }
44  }
45}

To retrieve the balances of a payment, you can use the following endpoint.

Use the details below to set up your request.

For the full API specification, see the API reference.

get

https://api.checkout.com/payments/{id}

In the response, you will be provided with the details of your payment. This includes a balances object containing the following fields:

Field name	Description
`total_authorized`	The total amount that has been authorized.
`total_voided`	The total amount that has been voided.
`available_to_void`	The total amount that is still available for voiding.
`total_captured`	The total amount that has been captured.
`available_to_capture`	The total amount that is still available for capture.
`total_refunded`	The total amount that has been refunded.
`available_to_refund`	The total amount that is still available for refund.


1{
2  "id": "pay_4gbjiuwysylutbdnxboxiebifq",
3  "requested_on": "2020-03-17T16:06:51Z",
4  "source": {
5    "id": "src_sp7e7ehmsqlevaqkzso2ajilue",
6    "type": "card",
7    "expiry_month": 12,
8    "expiry_year": 2025,
9    "scheme": "Visa",
10    "last4": "4242",
11    "fingerprint": "71580B426F1D190D29087FF265D8F48DF1AD34EDE41C27CBFF9D23C1A14D1776",
12    "bin": "424242",
13    "card_type": "CREDIT",
14    "card_category": "CONSUMER",
15    "issuer": "Test Bank",
16    "issuer_country": "US",
17    "product_id": "A",
18    "product_type": "Visa Traditional",
19    "avs_check": "S",
20    "cvv_check": "Y",
21    "payouts": true,
22    "fast_funds": "d"
23  },
24  "amount": 150,
25  "currency": "USD",
26  "payment_type": "Regular",
27  "reference": "ORD-752-814",
28  "status": "Captured",
29  "approved": true,
30  "risk": {
31    "flagged": false
32  },
33  "customer": {
34    "id": "cus_gp6e4vr7q4bufi4tcbn7oni65u"
35  },
36  "billing_descriptor": {
37    "name": "test payment",
38    "city": "Anytown"
39  },
40  "balances": {
41    "total_authorized": 150,
42    "total_voided": 0,
43    "available_to_void": 0,
44    "total_captured": 150,
45    "available_to_capture": 0,
46    "total_refunded": 0,
47    "available_to_refund": 150
48  },
49  "eci": "05",
50  "scheme_id": "961268269566117",
51  "_links": {
52    "self": {
53      "href": "https://api.sandbox.checkout.com/payments/pay_4gbjiuwysylutbdnxboxiebifq"
54    },
55    "actions": {
56      "href": "https://api.sandbox.checkout.com/payments/pay_4gbjiuwysylutbdnxboxiebifq/actions"
57    },
58    "refund": {
59      "href": "https://api.sandbox.checkout.com/payments/pay_4gbjiuwysylutbdnxboxiebifq/refunds"
60    }
61  }
62}

We've made some changes to our API

Authorize a payment

Request a final or estimated authorization

Information

Endpoints

Request example

Response example

Request an incremental authorization

Endpoints

Request example

Response example

Retrieve a payment's balances

Endpoints

Response example