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 authorization:
| Authorization type | Description |
|---|---|
Final | The authorization amount will not change before the payment is captured. |
Estimated | The authorization amount is an estimate. It may change through future incremental authorizations before it is captured. |
Incremental | This always follows an estimated authorization and does one of the following:
|
Partial | This captures part of the authorization amount if the cardholder has insufficient funds to cover the full amount. |
By default, all payment requests processed by Checkout.com are treated as final authorizations.
To explicitly request a final authorization, provide "authorization_type": "Final" in your payment request.
You can also specify whether you want to automatically capture the full amount using the capture field.
For partial captures, you must capture the payment manually.
post
https://api.checkout.com/payments
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 when you request a payment, you can request an estimated authorization.
For example, a car rental agency estimates an authorization amount that includes the rental fee, taxes, and mileage rates. However, when the vehicle is returned, the agency needs to increase the authorization amount due to additional fees.
Visa and Mastercard (globally), and American Express (in the US) support estimated authorizations for all merchant category codes (MCCs).
Information
Mastercard refers to estimated authorizations as 'preauthorizations'.
Information
Automatic payment capture is automatically disabled for estimated authorizations.
To perform an estimated authorization, provide "authorization_type": "Estimated" in your payment request.
post
https://api.checkout.com/payments
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. The authorization validity period varies per card scheme.
With a standard authorization request, the issuer declines the transaction with a 20051 response code if the cardholder has insufficient funds in their account to cover the full amount.
If you enable partial authorization for a Visa, Mastercard, or American Express (US only) payment, the issuer can return an authorization response for part 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 can do the following:
- Capture the available 80 GBP.
- Void the transaction, if you or the cardholder choose not to process the partial amount.
- Prompt the cardholder to use a different payment method and process the remaining 20 GBP in a new payment request.
To request a partial authorization, set the partial_authorization.enabled field in your request to true.
Note
We recommend that you do not automatically capture partially authorized payments. This reduces the likelihood of customers disputing unwanted transactions.
post
https://api.checkout.com/payments
If the response_code field in the response returns 10000, you can capture the full amount.
If the response code is 10010, inform the customer about the partial authorization and take one of the following actions, based on their response:
- If they accept the partial authorization request, you can capture the partial amount.
- If they do not accept, void the payment and ask the customer to use an alternative payment method, or retry the payment later.
To simulate an approval for a partial authorization in your sandbox environment, request a payment using one of the following test cards as the payment source:
| Scheme | Card number |
|---|---|
American Express (US only) |
|
Mastercard |
|
Visa |
|
Set the requested amount to one of the following values:
100001000
The response returns the following fields and values:
response_codeset to10010response_summaryset toPartial Value Approved- The partial approved amount:
"amount": "5000", if you requested"amount": "10000""amount": "700", if you requested"amount": "1000""amount": "840", if you requested"amount": "1000"with American Express
Card schemes set their own rules around how much time an authorization is valid for. You can 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
- A chargeback
The card schemes apply the following authorization validity periods:
| Card scheme | Validity period |
|---|---|
Mastercard | Seven days |
Visa |
|
American Express | Seven days |
Cartes Bancaires | Seven days |
Diners Club International | Seven days |
Discover | 10 days |