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 – Indicates to the card scheme that the amount being authorized will not change before the payment is captured
- Estimated – 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 – Always follows an estimated authorization and either increases the authorization amount (Visa and Mastercard globally, and American Express in the United States), 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
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 (globally), and American Express (in the United States) 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
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, Mastercard, or American Express (United States only) 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
If the response_code field in the response returns 10000, you can capture the full amount.
If the response_code field in the response returns 10010, notify 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 with one of the following test cards set as the payment source:
| Scheme | Card number |
|---|---|
American Express (US only) |
|
Mastercard |
|
Visa |
|
You can set the requested amount to one of the following values:
100001000
You should receive the following fields and values in your response:
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. 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 |