Pre-authorisation and authorisation adjustment

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 before the payment is captured. 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. Such changes to a pre-authorised payment are called authorisation adjustments.

When you consider implementing pre-authorisation and authorisation adjustment, take into account the following:

• Availability: support for authorisation adjustment is limited to specific credit card schemes, and also depends on your Merchant Category Code (MCC). It is ultimately up to the issuing bank whether they allow it.
• Validity: pre-authorisations and authorisations expire after a while, depending on the card scheme. Ideally, you capture the payment before the pre-authorisation expires.

Use cases

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

• Hospitality. For example, in a hotel:

  1. At check-in, the hotel pre-authorises payment of the room that the guest booked. At the same time, the hotel creates a shopper recognition token, 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-authorised amount by adjusting the authorisation.
  3. At check-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 recognition token 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.

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 don't 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 API.
• Final authorisation: use this when the final amount is agreed up front and the transaction will definitely be captured in full. It's not possible to adjust the authorised amount.

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 webhook notifications 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 one additional step 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 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:

1. Make sure that you have built an integration that can make a payment.
2. Set up webhook notifications. You'll need to rely on notifications to know whether the capture succeeded. If you use asynchronous authorisation adjustment, you'll also need to rely on notifications for the authorisation adjustment result.
3. Generate an API key. To adjust the authorisation and finalize the pre-authorised 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.

Also be aware that you 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.

Configure your account (Optional)

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 don't 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.

First step: Pre-authorise a payment

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

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

   • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. This includes:

   Parameter	Required	Description
   ProtocolVersion		3.0
   MessageClass		Service
   MessageCategory		Payment
   MessageType		Request
   ServiceID		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		Your unique ID for the POS system component to send this request from.
   POIID		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		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 Authorisation types	authorisationType=PreAuth: indicates this is a pre-authorisation request. See Adding data elements to your request to learn how to format SaleToAcquirerData.
     PaymentTransaction.AmountsReq		An object with: Currency: the transaction currency. RequestedAmount: the transaction amount.

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

   See the PaymentRequest API reference.

   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.

   If the pre-authorisation 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-authorised 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 authorised amount in minor units, which at this stage is equal to the original amount.
       • pspReference: the PSP reference of your pre-authorisation request.
       • adjustAuthorisationData: a blob with authorisation 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 authorisation request.

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

Optional step: Adjust the pre-authorisation

To modify the pre-authorised amount, make an authorisation 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.

Optional step: Extend the authorisation

To extend the authorisation period make an /payments/{paymentPspReference}/amountUpdates request with the same amount as the current balance on the authorisation. If you haven't adjusted the authorisation yet, this is the amount from the original pre-authorisation request. If you did adjust the authorisation, this is the amount from the last adjustment.

See Adjust the authorisation for instructions.

Last step: Finalize the pre-authorised payment

When you have made your last authorisation adjustment, you need to manually capture the payment to ensure the reserved funds are transferred to your account. Make sure that you have enabled manual capture, either for your account or for an individual transaction.

1. 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 customer 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 /payments/paymentPspReference/cancels request, where paymentPspReference is the pspReference of the original pre-authorisation. Refer to Cancel authorisation or capture) for more details.

2. When you are ready to capture the payment, make a POST request to the  /payments/paymentPspReference/captures  endpoint, specifying:

   • The path with:

     Parameter	Required	Description
     paymentPspReference		The pspReference of the authorisation being captured. You received this as part of the transactionID field in the response to your payment request. See Transaction identifier.

   • The request header with:

     Parameter	Required	Description
     content-type		application/json
     x-api-key		Your API key.

   • The request body with:

     Parameter	Required	Description
     amount		The currency and value 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.

3. 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.
   • status: received.
   • reference: your reference to this payment modification, for use in your reconciliation process.

4. Wait for the asynchronous notification. This informs you whether the final amount has been captured.
   If the capture is successful, this notification contains:

   • eventCode: CAPTURE
   • originalReference: The pspReference 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 the reason you received in the notification, fix the issue, and submit the capture request again.

Smart pre-authorisation

When pre-authorising a payment, certain card schemes do not support incremental adjustments. Because this is validated during the authorisation adjustment step, you cannot know in advance 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 authorisation adjustments. If it does, the terminal continues with the pre-authorisation request.
If the card doesn't support authorisation adjustment, the terminal checks and presents the shopper with the list of supported cards to choose from. They can then use a different card and continue with the pre-authorisation request.

To enable Smart pre-auth:

1. Log in to your Customer Area
2. Go to Point of sale > Terminal settings > Payment features.
3. Under Pre-authorization > Smart pre-auth, select the pencil icon and then Enabled.
4. At the bottom, select Save.

See also