Authorize a payment
A payment authorization is the process of requesting the card scheme to verify the payment details. If authorization is successful, funds are reserved so that you can capture the payment at a later date.
You can perform the following types of authorizations:
- final, which indicates to the card scheme that the amount being authorized will not change before the payment is captured
- estimated, which indicates to the card scheme that the amount being authorized is an estimate and may change via future incremental authorizations before it's captured
- incremental, which always follows an estimated authorization and either increases the authorization amount (Visa and Mastercard), or extends the authorization validity period (Mastercard only)
- partial, if you want the option to capture a portion of the authorization amount if the cardholder does not have sufficient funds to cover the full amount
By default, all payment requests processed by Checkout.com are treated as final authorizations.
Alternatively, you can explicitly perform a final authorization by passing "authorization_type": "Final"
in the request.
When you perform a final authorization, you can also specify whether the payment should be fully captured automatically with the capture
field. For partial captures, you must capture the payment manually.
For the full API specification, see the API reference.
Information
The Payments API supports idempotency. You can safely retry API requests without the risk of duplicate requests.
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": "Final",12"processing_channel_id": "mer_q4dbxom5jbgudnjzjpz7j2z6uq",13"capture": false14}
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},44"customer": {45"id": "cus_sozpnpktte5uzooigxau35uloq"46},47"processed_on": "2020-03-16T22:11:24Z",48"reference": "ORD-752-814",49"processing": {50"acquirer_transaction_id": "8367314942",51"retrieval_reference_number": "162588399162"52},53"_links": {54"self": {55"href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua"56},57"actions": {58"href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/actions"59},60"authorize": {61"href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/authorizations"62},63"capture": {64"href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/captures"65},66"void": {67"href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/voids"68}69}70}
The balances
object returned in the response provides an overview of the payment’s balances, as well as the amounts that are available for subsequent payment actions.
If you do not know the final amount for a transaction at the time you request a payment, you can perform an estimated authorization.
For example, a car rental agency may estimate an authorization amount which includes the value of the rental, taxes, and mileage rates. However, when the vehicle is returned, they may need to increase the authorization amount due to additional fees.
Visa and Mastercard both support estimated authorizations for all merchant category codes (MCCs).
Information
Mastercard refers to estimated authorizations as 'preauthorizations'.
Automatic payment capture is automatically disabled for estimated authorizations.
To perform an estimated authorization, pass "authorization_type": "Estimated"
in the request.
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}
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},44"customer": {45"id": "cus_sozpnpktte5uzooigxau35uloq"46},47"processed_on": "2020-03-16T22:11:24Z",48"reference": "ORD-752-814",49"processing": {50"acquirer_transaction_id": "8367314942",51"retrieval_reference_number": "162588399162"52},53"_links": {54"self": {55"href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua"56},57"actions": {58"href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/actions"59},60"authorize": {61"href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/authorizations"62},63"capture": {64"href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/captures"65},66"void": {67"href": "https://api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/voids"68}69}70}
The balances
object returned in the response provides an overview of the payment’s balances, as well as the amounts that are available for subsequent payment actions.
If you need to increase the authorization amount before you capture the payment, you can perform an incremental authorization.
After performing an estimated authorization, you have a set number of days to capture the payment before it expires. This authorization validity period varies for each card scheme.
With a standard authorization request, an issuer will decline a transaction with a 20051 - Insufficient funds
response code if the cardholder does not have sufficient funds in their account to cover the full amount.
If you enable partial authorization for a Visa or Mastercard payment, the issuer can return an authorization response for a portion of the full amount instead.
For example, if the full authorization amount is 100 GBP and the cardholder has 80 GBP in their account, with an approved partial authorization you'll have the option to:
- capture the available 80 GBP
- void the transaction, if you or the cardholder choose not to process the partial amount
- return to the cardholder to request a new payment method and process the remaining 20 GBP in a new payment request
To enable partial authorization for a payment, set the partial_authorization.enabled
field in your request to true
.
Note
To reduce the likelihood of a customer disputing an unwanted transaction, we recommend that you do not automatically capture partially authorized payments.
post
https://api.checkout.com/payments
1{2"amount": 10000,3"currency": "GBP",4"source": {5"type": "card",6"expiry_month": "12",7"expiry_year": "2027",8"cvv": "153",9"number": "4757337282365488"10},11"partial_authorization": {12"enabled": true13},14"capture": false15}
If the response_code
field in the response is:
10000
– You can request to capture the full amount.10010
– You must prompt the customer to approve the partial authorization amount. If they accept, you can request to capture the partial authorization amount. If they don't accept, void the payment and ask the customer to either select an alternative payment method, or retry the payment later.
1{2"id": "pay_p2l6rr42k2qupd7576qpjin2py",3"action_id": "act_dx4mex77fktu5c2an77zpjqgke",4"amount": 5000,5"amount_requested": 10000,6"currency": "GBP",7"approved": true,8"status": "Authorized",9"auth_code": "PWVHML",10"response_code": "10010",11"response_summary": "Partial Value Approved",12"balances": {13"total_authorized": 5000,14"total_voided": 0,15"available_to_void": 5000,16"total_captured": 0,17"available_to_capture": 5000,18"total_refunded": 0,19"available_to_refund": 020},21"risk": {22"flagged": false,23"score": 0.024},25"source": {26"id": "src_voxmd5a6j7uupkow55r4ewmd3m",27"type": "card",28"billing_address": {29"address_line1": "123 High St.",30"address_line2": "Flat 456",31"city": "London",32"zip": "SW1A 1AA",33"country": "GB"34},35"phone": {36"number": "79460000",37"country_code": "44"38},39"expiry_month": 12,40"expiry_year": 2027,41"scheme": "Visa",42"last4": "5488",43"fingerprint": "DDA617DF9E84C145B932DD09D4DDCB3A32C80C34E6CDBFFEEF2D2423FECC4ABF",44"bin": "416549",45"card_type": "DEBIT",46"card_category": "CONSUMER",47"issuer": "Test Bank",48"issuer_country": "GB",49"product_id": "I",50"product_type": "Visa Infinite",51"avs_check": "N",52"cvv_check": "Y",53"payment_account_reference": "V0010013822353374818836592526"54},55"customer": {56"id": "cus_qeqdzlrxgmeexhrijsmdccm7oi"57},58"processed_on": "2024-01-18T13:27:37.7726822Z",59"scheme_id": "484018484577883",60"processing": {61"acquirer_transaction_id": "531620484018484577883",62"retrieval_reference_number": "401832531620",63"merchant_category_code": "0742",64"scheme_merchant_id": "516529",65"scheme": "VISA",66"partner_response_code": "10",67"acquirer_name": "Checkout Visa",68"acquirer_country_code": "GB",69"aft": false70},71"expires_on": "2024-02-17T13:27:37.7726822Z",72"_links": {73"self": {74"href": "https://api.checkout.com/payments/pay_p2l6rr42k2qupd7576qpjin2py"75},76"actions": {77"href": "https://api.checkout.com/payments/pay_p2l6rr42k2qupd7576qpjin2py/actions"78},79"capture": {80"href": "https://api.checkout.com/payments/pay_p2l6rr42k2qupd7576qpjin2py/captures"81},82"void": {83"href": "https://api.checkout.com/payments/pay_p2l6rr42k2qupd7576qpjin2py/voids"84}85}86}
To simulate an approval for a partial authorization in your test environment, request a payment with one of the following test cards set as the payment source
:
Scheme | Card number |
---|---|
Mastercard |
|
Visa |
|
You can set the requested amount
to one of the following values:
10000
1000
You should receive the following fields and values in your response:
response_code
set to10010
response_summary
set toPartial Value Approved
- the partial approved amount:
"amount": "5000"
, if you requested"amount": "10000"
"amount": "700"
, if you requested"amount": "1000"
Card schemes set their own rules around how much time an authorization is valid for. It's possible to successfully capture a payment after an authorization has expired, but this increases the risk of:
- a failed capture
- increased interchange fees
- card scheme transaction fees
- higher risk of cardholder chargeback
The following tables show the authorization validity periods as set by the card schemes:
Card scheme | Validity period |
---|---|
Mastercard | 7 days |
Visa |
|
American Express | 7 days |
Cartes Bancaires | 7 days |
Diners Club International | 7 days |
Discover | 10 days |