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": 20257},8"amount": 100,9"currency": "USD",10"reference": "ORD-752-814",11"authorization_type": "Estimated",12"processing_channel_id": "mer_q4dbxom5jbgudnjzjpz7j2z6uq",13"capture": false14}
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": 022},23"risk": {24"flagged": false25},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}
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": 021},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 |
---|---|
| The total amount that has been authorized. |
| The total amount that has been voided. |
| The total amount that is still available for voiding. |
| The total amount that has been captured. |
| The total amount that is still available for capture. |
| The total amount that has been refunded. |
| 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": false32},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": 15048},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}