Skip to content

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.

Request a final or estimated authorization

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.

Endpoints

For the full API specification, see the API reference.

post

https://api.checkout.com/payments

Request example

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
}

Response example

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
}

Request an incremental authorization

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.

Endpoints

For the full API specification, see the API reference.

post

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

Request example

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

Response example

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

Retrieve a payment's balances

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

Use the details below to set up your request.

Endpoints

For the full API specification, see the API reference.

get

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

Response example

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

Field nameDescription

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
}