Point-of-sale icon

Authorization adjustment

Pre-authorize a payment, adjust the authorized amount, and capture the payment.

In a basic payment flow, the payable amount from your payment request is authorized and then captured. But sometimes you want to change the amount or extend the length of the authorization. Using the authorization type pre-authorization for your payment request, you can increase or decrease the authorized amount at a later stage, and then capture the payment manually. Changes to a pre-authorized payment are called "authorization adjustments".

When you consider implementing authorization adjustment, take into account the following:

  • Availability: support for authorization adjustment is limited to specific credit card schemes and Merchant Category Codes (MCC). It is ultimately up to the issuing bank whether they allow it. You can enable Smart Pre-auth to check during pre-authorization if the card scheme supports authorization adjustments.
  • Expiration: pre-authorizations and authorizations expire after a while, depending on the card scheme. Ideally, you capture the payment before the pre-authorization expires.
The process to adjust an authorized amount is as follows:
  1. To indicate that you will probably make changes later, you use the authorization type pre-authorization in your payment request.
    The payment is pre-authorized for the amount specified in the payment request.
  2. When the amount due increases (or decreases), you send a request to adjust the pre-authorized amount.
    Each time that the amount due changes or the validity period of the authorization is about to expire, you send another authorization adjustment request.
  3. After your last authorization adjustment, you manually capture the payment.

Use cases

There are several use cases for adjusting a pre-authorized amount:

  • Hospitality. For example, in a hotel:
    1. Just before the guest checks in, or when the guest checks in using an app or in person, the hotel pre-authorizes payment of the guest's room. At the same time, the hotel stores the shopper's payment information , to be able to apply late charges when necessary.
    2. During their stay, the guest incurs expenses at the hotel facilities. The hotel adds these expenses to the pre-authorized amount by adjusting the authorization.
    3. 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.
    4. If necessary, the hotel charges the guest after they have left, using the shopper's stored payment details for a new payment.
  • Tipping in regions and industries where it is customary that the guest adds a tip on the receipt after they have presented their card.

  • Cross-channel customer journeys. For example: the shopper pre-orders a product in a web shop, and after a long delivery time goes to the store to make the payment and collect the product.

Authorization type

For some card schemes, you can set payment requests to be handled as either a pre-authorization or a final authorization.

  • Pre-authorization: this authorization type verifies that the shopper's account is valid and has sufficient funds to cover a transaction, but does not debit the account. It is intended for use cases as described above, when you don't yet know the amount to be captured. It allows you to increase or decrease the initially authorized amount at a later point in time.

  • Final authorization: the final amount is agreed up front and the transaction will be captured in full. This is the default authorization type, and it doesn't allow you to adjust the authorized amount later.

By default, Adyen handles all card payment requests as final authorizations. To set an authorization type, you can either:

  • Define the default authorization type at the merchant account level for all card transactions. See Configure your account.
  • Manually specify authorizationType PreAuth or authorizationType FinalAuth in each payment request. See Pre-authorize a payment.

Asynchronous or synchronous adjustment

There are two ways to implement pre-authorization:

  • Asynchronous authorization adjustment: you refer to a payment using the PSP reference that you received in the response to your pre-authorization request. In each authorization adjustment request, and in the final capture request, you specify this first PSP reference.

    Asynchronous adjustment is easier to implement, but it is not immediately clear if the adjustment succeeded. You must set up webhooks to receive updates and to know if the final amount was authorized before you capture the payment.

  • Synchronous authorization adjustment: you pass an adjustAuthorisationData blob from one request to the next, to enable us to keep track of the latest amount. You receive the first blob in the response to your pre-authorization request. In your first authorization adjustment request, you specify the blob you received for the pre-authorization, 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 more effort to implement, because you need to keep track of the latest blob. The advantage is that you receive the adjustment result synchronously. In this way you immediately know if the final amount was authorized before you capture the payment.

    If at any point 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-authorization:

  1. Build an integration that can make a payment.
  2. Set up webhooks. You'll need to rely on webhooks to know whether the capture succeeded. If you use asynchronous authorization adjustment, you'll also need to rely on webhooks for the authorization adjustment result.
  3. Generate an API key. To adjust the authorization and finalize the pre-authorized payment, you need to have an API key.

    If you are using cloud-based communications, you can use the existing API key that you use for Terminal API requests.

  4. Implement logic on your end to decide when to use the pre-authorization flow, and to calculate the amount when you make an authorization adjustment.

Configure your account (Optional)

There are various aspects of your account that you may want to configure for pre-authorization and authorization adjustment:

  • Synchronous authorization adjustment: if you want to use synchronous authorization adjustment, ask our Support Team to enable this. You will then receive the initial adjustAuthorisationData blob with your pre-authorization request and subsequently receive the authorization adjustment results synchronously.

  • Default authorization type: if you only do pre-authorization payment requests, you can ask our Support Team to set your default authorization type to PreAuth so that you don't have to specify it in your payment requests.

    If you want to do both pre-authorization payment requests and regular payment requests, we recommend you specify the authorization type in all payment requests.

  • Manual capture: to capture payments in the authorization adjustment flow, manual capture must be enabled. You can set this for your account, but then all payments require manual capture. The alternative is to enable manual capture in the individual pre-authorization requests.

Enable smart pre-authorization (Optional)

Certain card schemes do not support incremental adjustments. Because this is validated during the authorization adjustment step, you cannot know in advance, at the pre-authorization step, if you should accept the customer's card.

The Smart Pre-auth feature lets your payment terminal check if the card presented by the customer supports authorization adjustments. If it does, the terminal continues with the pre-authorization request.
If the card doesn't support authorization adjustment, the terminal presents the shopper with the list of supported cards to choose from. They can then use a different card and continue with the payment.

To enable Smart Pre-auth:

  1. Log in to your Customer Area
  2. Go to In-person payments > Terminal settings > Payment features.
  3. Under Pre-authorization > Smart Pre-auth, select the pencil icon and then Enable.
  4. Select Save.

Smart Pre-auth is not available for Mail Order/Telephone Order (MOTO) and Manual Key Entry (MKE).

Step 1: Pre-authorize a payment

To start the pre-authorization payment flow, make a PaymentRequest with an authorization type of PreAuth:

  1. Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Payment
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
      SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].
    • PaymentRequest: the request body. This includes:

      Parameter Required Description
      SaleData.SaleTransactionID -white_check_mark- An object with:
      • TransactionID: your reference to identify a payment. We recommend using a unique value per payment.
      • TimeStamp: date and time of the request in UTC format.
      SaleData.SaleToAcquirerData See Authorization type A string with:
      • authorisationType=PreAuth: indicates this is a pre-authorization request.
      • manualCapture=true to enable manual capture for this request, if you haven't enabled manual capture for your account.

      See Adding data elements to your request to learn how to format SaleToAcquirerData.
      PaymentTransaction.AmountsReq -white_check_mark- An object with:
      • Currency: the transaction currency.
      • RequestedAmount: the transaction amount.

    The following example shows how to initiate pre-authorization for a payment of EUR 150.00.

    The customer presents their card to the payment terminal. The terminal collects the payment details and sends the request for the original amount to the Adyen payments platform for processing.

  2. Check the response. If the pre-authorization is successful:

    • Approved is displayed on the terminal display.
    • The payment result contains:

      • POIData.POITransactionID.TransactionID: Transaction identifier for the payment, in the format Tender_reference.PSP_reference.

      • PaymentResult: payment method data including:

        • AmountsResp: the AuthorizedAmount and Currency of the pre-authorized payment.

      • Response.Result: Success

      • Response.AdditionalResponse: additional transaction data. Depending on the format you used in the request, you receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object. This includes:

        • posadditionalamounts.originalAmountValue: the original amount in minor units.
        • authorisedAmountValue: the authorized amount in minor units, which at this stage is equal to the original amount.
        • pspReference: the PSP reference of your pre-authorization request.
        • adjustAuthorisationData: a blob with authorization data. You only receive this if the synchronous flow is enabled for your account.

    The following example shows the response to a EUR 150.00 authorization request.

  3. Store the pspReference and the adjustAuthorisationData from the AdditionalResponse for later use when adjusting the authorization or capturing the payment.

Step 2: Adjust the pre-authorized amount

To increase or decrease the pre-authorized amount or to extend the authorization, make an authorization adjustment request.

This step involves making a request to the Adyen backend directly. This is not a Terminal API request to the terminal itself or the Cloud endpoint for the terminal.

When building or testing the flow, make sure there is at least a 5 second delay between the pre-authorization and the authorization adjustment.

  1. Make a POST /payments/{paymentPspReference}/amountUpdates request, where {paymentPspReference} is the PSP reference from the pre-authorization response. Specify:

    Parameter Required Description
    amount -white_check_mark- The currency and value of the new amount in minor units. This is the sum of the pre-authorized amount and the additional amount.

    If this is not the first authorization adjustment, it is the sum of the pre-authorized amount plus all additional amounts.
    merchantAccount -white_check_mark- The name of your merchant account that is used to process the payment.
    industryUsage delayedCharge
    reference Your reference to this payment modification, for use in your reconciliation process.

    The following example shows how to add a charge of EUR 64.15 to a pre-authorized amount of EUR 150.00.

  2. Note that the /amountUpdates response contains:

    • pspReference: the PSP reference for this /amountUpdates request. This is different from the PSP reference of the pre-authorization request.
    • status: received
  3. Wait for the AUTHORISATION_ADJUSTMENT webhook. This informs you whether the new amount has been authorized.

Extending the authorization

Authorizations expire after a while. To extend the authorization period, follow the same instructions as for adjusting the pre-authorized amount, but use the same amount as the current balance on the authorization:

  • If you haven't adjusted the authorization yet, use the amount from the original pre-authorization request.
  • If you did adjust the authorization, use the amount from the last adjustment. When using the asynchronous adjustment flow, check the amount in the AUTHORISATION_ADJUSTMENT webhook.

Step 3: Capture the payment

After you make your last authorization adjustment, you must manually capture the payment to transfer the reserved funds to your account.

Always double-check that you have completed all authorization adjustments for the payment before you capture it. Captures are done asynchronously, so it may seem that the payment hasn't been completely captured yet and that it is still possible to adjust the authorization.

  1. Decide whether you are ready to capture the payment:

    • If there are additional charges to make, first adjust the authorization.

    • If the customer wants to settle the bill using a different payment method than the one used for the pre-authorization, do not capture the payment. Instead, cancel the pre-authorization by sending a POST /payments/{paymentPspReference}/cancels request, where {paymentPspReference} is the PSP reference from the pre-authorization response.

  2. When you are ready to capture the payment, make a POST /payments/{paymentPspReference}/captures request, where {paymentPspReference} is the PSP reference from the pre-authorization response. Specify:

    Parameter Required Description
    amount -white_check_mark- The currency of the final amount and its value in minor units. This is the sum of the original, pre-authorized amount and all later adjustments.
    merchantAccount -white_check_mark- The name of your merchant account that is used to process the payment.
    reference Your reference to this payment modification, for use in your reconciliation process.
  3. When you receive the /captures response, note the following:

    • pspReference: the PSP reference associated with this /captures request. This is different from the PSP reference associated with the pre-authorization request.
    • status: received
    • reference: your reference to this payment modification, for use in your reconciliation process.
  4. Wait for the webhook. This informs you whether the final amount has been captured.
    If the capture is successful, this event contains:

    • eventCode: CAPTURE
    • originalReference: The pspReference of the pre-authorization.
    • pspReference: The PSP reference associated with this /captures request.
    • success: true

    If the capture fails, the webhook contains success: false. Review the reason you received in the webhook, fix the issue, and submit the /captures request again.

If you need to charge the customer for an additional amount after they have left, and you stored the customer's payment details with your pre-authorisation request, you can apply these late charges in a recurring payment request using the token.

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:

  1. Log in to your live Customer Area.
  2. Switch to your merchant account.
  3. Select Settings > Payment methods.
  4. 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
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 show the authorization validity periods for the global card schemes that allow authorization adjustment.

American Express

Scheme Debit/credit Environment Authorization type MCC Days
Amex All All All All 7 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 MCCs 30 days

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.

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

Visa can reject capturing payments after the seven-day validity of the authorization has expired, 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.

Testing

Our test environment supports testing the whole authorization adjustment flow. For the pre-authorization request you can use our POS test cards.

See also