In a basic payment flow, the payable amount from your payment request is authorised and then captured. But sometimes you may want to change the amount or extend the length of the authorisation. You can enable this using the authorisation type pre-authorisation with your payment request. In this payment flow you can increase or decrease the authorised amount at a later stage, and then capture the payment. We refer to these changes to a pre-authorised payment as authorisation adjustments.
Authorisation adjustment is currently available for Discover, Mastercard, Visa, and American Express. Support is ultimately up to the issuer. See Availability for more information.
Use cases
There are several use cases for adjusting an authorisation:
-
Hospitality. For example, in a hotel:
- At the checkout page of the hotel's website or app, the hotel pre-authorises payment of the room that the guest booked. At the same time, the hotel stores the shopper's payment information, to be able to apply late charges when necessary.
- During their stay, the guest incurs expenses at the hotel facilities. The hotel adds these expenses to the pre-authorised amount by adjusting the authorisation.
- When the guest checks out, the hotel captures the final amount, or cancels the payment if the guest prefers to settle their bill with a different payment method.
- If necessary, the hotel charges the guest after they have left, using the shopper's stored payment details for a new payment.
-
Pre-ordering items. For example, a shopper pre-orders a video game that will be released three months later. The video game seller authorises the payment, but as they can only ship the product three months later, they need to extend the authorisation validity.
Authorisation types
For some card schemes, you can set card payment requests to be handled as either a pre-authorisation or a final authorisation.
- Pre-authorisation: This is intended for use cases as described above, when you do not yet know the amount to be captured. It allows you to increase or decrease the initially authorised amount at a later point in time using the /adjustAuthorisation endpoint.
- Final authorisation: Use this when the final amount is agreed up front and the transaction will definitely be captured in full. It is not possible to adjust the authorised amount.
By default, Adyen handles all card payment requests as final authorisations.
To set an authorisation type, you can either:
- Define the default authorisation type at the merchant account level for all card transactions. See Configure your account.
- Manually specify the authorisation type (PreAuth or FinalAuth) in each payment request. See Pre-authorise a payment.
Asynchronous or synchronous adjustment
There are two ways to implement pre-authorisation:
-
With asynchronous authorisation adjustment, you refer to a payment using the PSP reference that you received in the response to your pre-authorisation request. In each authorisation adjustment request as well as in the final capture request, you only need to specify this first PSP reference.
Asynchronous adjustment is easier to implement, but it is not immediately clear if the adjustment succeeded. You need to set up webhooks to receive updates and to know if the final amount was authorised before you capture the payment.
-
With synchronous authorisation adjustment, you pass an
adjustAuthorisationData
blob from one authorisation adjustment to the next, to enable us to keep track of the latest amount. You receive the first blob in the response to your pre-authorisation request. In your first authorisation adjustment request, you specify the blob you received for the pre-authorisation, and you receive a new blob in the response. In your next adjustment, you specify the blob that you received in the response for the previous adjustment, and so on.Synchronous adjustment requires an additional step to implement, because you need to keep track of the latest blob to submit it in the subsequent adjust authorisation request. The advantage is that you receive the adjustment result synchronously. In this way you immediately know if the final amount was authorised before you capture the payment.
If at some stage you fail to pass the blob, the flow falls back to asynchronous adjustment and it is no longer possible to return to synchronous adjustment for that payment.
Before you begin
Before you configure and use pre-authorisation:
- Make sure that you have built an integration that can make a payment.
- Set up webhooks. You'll need to rely on webhooks to know whether the capture succeeded. If you use asynchronous authorisation adjustment, you'll also need to rely on webhooks for the authorisation adjustment result.
You also need to implement logic on your end, for example to decide when to use the pre-authorisation flow, and to calculate the amount when you make an authorisation adjustment.
(Optional) Configure your account
There are two aspects of your account that you may want to configure for pre-authorisation and authorisation adjustment:
-
Synchronous authorisation adjustment: To receive the initial
adjustAuthorisationData
blob with your pre-authorisation request and to subsequently receive the authorisation adjustment results synchronously, ask our Support Team to enable this. -
Default authorisation type: If you only do pre-authorisation payment requests, you can ask our Support Team to set your default authorisation type to PreAuth so that you do not have to specify it in your payment requests.
If you want to do both pre-authorisation payment requests and regular payment requests, we recommend you specify the authorisation type in all payment requests. Pre-authorised transactions incur scheme fees.
Step 1: Pre-authorise a payment
-
Make a payment request, and additionally specify:
additionalData.authorisationType
:PreAuth
-
Store the
pspReference
from the response for later use when adjusting the authorisation or capturing the payment.
Step 2: (Optional) Modify the authorisation
You cannot make a zero-value authorisation when you adjust an authorisation.
Adjust the pre-authorisation amount
To modify the pre-authorised amount, make an authorisation adjustment request.
Extend the authorisation
To extend the authorisation period make an /adjustAuthorisation request with the same amount as the current balance on the authorisation:
- If you haven't adjusted the authorisation yet, use the amount from the original pre-authorisation request.
- If you did adjust the authorisation, use the amount from the last adjustment.
For Mastercard, the request made to adjust the pre-authorised amount automatically extends the validity period of the authorisation. So, if you have adjusted an authorisation, you do not immediately have to extend its validity.
We strongly recommend you to use the asynchronous flow to extend the authorisation. Visa only supports the asynchronous flow.
See Adjust the authorisation for instructions. To check the status of the authorisation (the original and the extension), make sure to consume webhooks.
For Visa and American Express, the issuer can refuse the request to extend the authorisation period. This refusal terminates the initially authorised payment. Check that you consume the webhook event to handle this situation by either withholding shipment or authorising the card again at a later time.
Step 3: Finalize the pre-authorised payment
When you have made your last authorisation adjustment, you need to manually capture the payment to transfer the reserved funds to your account:
-
Decide whether you are ready to capture the payment:
-
Are there any additional charges to be made?
If yes, adjust the authorisation first (see Adjust the authorisation). -
Does the shopper want to settle the bill using a different payment method than the one used for the pre-authorisation?
If yes, do not capture the payment. Instead, cancel the pre-authorisation:-
Make a /cancel request specifying the
pspReference
of the original pre-authorisation. Refer to Cancel authorisation for more details.
-
-
-
When you are ready to capture the payment, make a POST request to the /capture endpoint, specifying:
Parameter Required Description originalReference
The pspReference
of the original pre-authorisation. You received this in the response to your pre-authorisation request.modificationAmount
The currency
andvalue
of the final amount in minor units. This is the sum of the original, pre-authorised amount and all later adjustments.reference
Your reference to this payment modification, for use in your reconciliation process. merchantAccount
The name of your merchant account that is used to process the payment. -
When you receive the /capture response, note the following:
pspReference
: The PSP reference associated with this /capture request. Note that this is different from the PSP reference associated with the pre-authorisation request.response
: [capture-received].additionalData.merchantReference
: Your reference to this payment modification, for use in your reconciliation process.
-
Wait for the webhook event. This informs you whether the final amount has been captured.
If the capture is successful, this event contains:eventCode
: CAPTUREoriginalReference
: ThepspReference
of the pre-authorisation.pspReference
: The PSP reference associated with this /capture` request.success
: true
If
success
is false then your capture request failed. Review thereason
you received in the webhook event, fix the issue, and submit the capture request again.
If you need to charge the guest for an additional amount after they have left, and you stored your shopper's payment details (token) with your pre-authorisation request, you can apply these late charges in a recurring payment request using the token. See Recurring payments.
You can combine the steps listed before to fulfill your use case. For example, if you want to do multiple partial captures, modify the amount authorised after the first partial capture. To do so, pre-authorise a payment, partially capture the payment, and then adjust the authorisation amount.
Availability
Card schemes set specific rules around which businesses can adjust authorizations. Your eligibility is determined by your Merchant Category Code (MCC), but note that schemes use different MCCs for the same business type.
To view your MCCs for each payment method:
- Log in to your live Customer Area.
- Switch to your merchant account.
- Select Settings > Payment methods.
- View the MCC column for the relevant payment methods.
Use the following table to see if authorization adjustment is available for your business:
Card scheme | Available for Merchant Category Codes (MCC) | |
---|---|---|
American Express | All MCCs except 5542 | |
Discover | 3351-3441, 3501-3999, 4111, 4112, 4121, 4131, 4411, 4457, 5499, 5812, 5813, 7011, 7033, 7996, 7394, 7512, 7513, 7519, 7999 | |
Mastercard | All MCCs except 5542 | |
Mexico Domestic (Network MX) | Card present: 4722, 5541, 5542, 5812, 5813, 8062, multiple MCCs for car rental, entertainment, and hotels Card not present: 4011, 4112, 4121, 4131, 4816, 5300, 5310, 5311, 5331, 5411, 5422, 5814, all air transportation |
|
Visa | All MCCs except 5542 Authorization adjustment does not work for V Pay cards. |
Expiration of authorizations
You can only adjust an authorization that hasn't expired yet. There are two authorization validity periods to take into account:
-
For the global card schemes, Adyen expires authorization requests automatically after 28 days from the day the payment is authorized. Contact our Support Team if you want to change this default setting, and configure custom authorization validity periods for specific merchant accounts and card schemes.
-
Card schemes have their own rules on authorization validity, and can expire an authorization before or after the scheme's official authorization validity period. It is possible to successfully capture a payment after an authorization has expired, but this practice increases the risk of:
- A failed capture.
- Increased interchange fees.
- Card scheme transaction fees.
- Higher risk of cardholder chargeback.
The following tables include information on authorization validity periods for major card schemes that allow authorization adjustment.
American Express
Scheme | Debit/credit | Environment | Authorization type | MCC | Days |
---|---|---|---|---|---|
Amex | All | All | All | All | 7 days |
Cartes Bancaires
Scheme | Debit/credit | Environment | Authorization type | MCC | Days |
---|---|---|---|---|---|
Carte Bancaires | All | All | All | All | 13 days |
Diners
Scheme | Debit/credit | Environment | Authorization type | MCC | Days |
---|---|---|---|---|---|
Diners | All | MOTO | All | All | 7 days |
Diners | Debit | All | All | All | 7 days |
Diners | Credit | All | All | All | 30 days |
Diners | All | All | All | Car Rental, Hotel/Lodging | 30 days |
Discover
Scheme | Debit/credit | Environment | Authorization type | MCC | Days |
---|---|---|---|---|---|
Discover | All | All | All | All | 10 days |
Discover | All | All | All | Car Rental, Hotel/Lodging | 30 days |
JCB
Scheme | Debit/credit | Environment | Authorization type | MCC | Days |
---|---|---|---|---|---|
JCB | All | All | All | All | 1 year |
JCB | All | All | Pre-auth | Hotel and Car rental | Time of stay/rental |
Mastercard
Scheme | Debit/credit | Environment | Authorization type | MCC | Days |
---|---|---|---|---|---|
Mastercard | All | All | Final auth | All | 7 days |
Mastercard | All | All | Pre-auth | All | 30 days |
Capturing Mastercard payments can be successful even when the authorization has expired after seven or 30 days. For domestic transactions in the US and Canada, there is a late capture fee.
Mexico Domestic
Scheme | Debit/credit | Environment | Authorization type | MCC | Days |
---|---|---|---|---|---|
Network MX | Debit | All | Final auth | All | 7 days |
Network MX | Credit | All | Final auth | All | 30 days |
Network MX | Debit | All | Pre-auth | All | 30 days |
Network MX | Credit | All | Pre-auth | All | 120 days |
Visa
Scheme | Debit/credit | Environment | Authorization type | MCC | Days |
---|---|---|---|---|---|
Visa electron | All | All | All | All | 5 days |
Visa | All | POS | All | All | 1 day |
Visa | All | Ecommerce | All | All | 7 days |
Visa | All | All | Pre-Auth | Cruise, Lodging, Vehicle Rental | 31 days |
Visa | All | Subscriptions and UnscheduledCardOnFile | All | All | 1 day |
Visa | All | CnP | All | 4121 | 1 day |
Capturing Visa payments after the seven-day authorization validity period can be rejected by Visa, unless other rules apply. For domestic transactions in the US, the applicable interchange fee can increase when delaying a capture for more than two days.