Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Pre-authorisation

Pre-authorise a payment, adjust the authorised amount, and capture the payment.

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 do this using pre-authorisation. 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.

Authorisation adjustment is currently available for Discover, Mastercard, and Visa. Support is ultimately up to the issuer.

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.

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, make sure you have:

  • Read and understood our Terminal API fundamentals.
  • Built an integration that can make a payment.
  • 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.

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.

Step 1 (Optional): Configure your account

There are two aspects of your account that you may want to configure for pre-authorisation:

  • Synchronous authorisation adjustment: To receive authorisation adjustment results synchronously, ask our POS Support Team to enable this.

  • Default authorisation type: Usually the default authorisation type is Final, which means the payment is automatically captured when it is authorised. Because this is the default, you don't need to specify it in your payment requests. With pre-authorisation however, you need to specify an authorisation type of PreAuth in your payment request. If you only do pre-authorisation payment requests, you can ask our POS 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 normal payment requests, we recommend you specify the authorisation type in all payment requests.

Step 2: 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: This follows the standard MessageHeader structure, explained in Terminal API fundamentals, which includes:

      • ProtocolVersion: 3.0
      • MessageClass: Service
      • MessageCategory: Payment.
      • MessageType: Request
      • SaleID: Your unique ID for the cash register.
      • ServiceID: Your unique ID for this transaction attempt, consisting of 1-10 alphanumeric characters. This value needs to be unique within the last 48 hours.
      • POIID: Unique ID of the terminal. This indicates which terminal the payment will be routed to.
    • PaymentRequest: The request body for the pre-authorisation request must include:

      • SaleData.SaleTransactionID.TransactionID: Your unique reference for this payment request.
      • SaleData.SaleTransactionID.TimeStamp: Date and time of the payment request, in UTC format.
      • SaleData.SaleToAcquirerData:
        • authorisationType=PreAuth: Indicates this is a pre-authorisation request.
        • Any other key-value pairs you want to pass, for example for shopper recognition purposes.
      • PaymentTransaction.AmountsReq.Currency: The currency of the transaction.
      • PaymentTransaction.AmountsReq.RequestedAmount: The transaction amount.

    The following example shows how you would initiate pre-authorisation for a 150.00 EUR payment.

    For more information on the Terminal API request structure, refer to the Terminal API fundamentals.

    Pre-authorisation request
    {
      "SaleToPOIRequest":{
        "MessageHeader":{
          "ProtocolVersion":"3.0",
          "MessageClass":"Service",
          "MessageCategory":"Payment",
          "MessageType":"Request",
          "SaleID":"POSSystemID12345",
          "ServiceID":"0207111104",
          "POIID":"P400Plus-275688710"
        },
        "PaymentRequest":{
          "SaleData":{
            "SaleTransactionID":{
              "TransactionID":"27908",
              "TimeStamp":"2019-03-07T10:11:04+00:00"
            },
            "SaleToAcquirerData":"authorisationType=PreAuth"
          },
          "PaymentTransaction":{
            "AmountsReq":{
              "Currency":"EUR",
              "RequestedAmount":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.

    If the pre-authorisation is succesful:

    • 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: A base64 string. When decoded, this is a JSON object with additional transaction data. This includes:
        • posadditionalamounts.originalAmountValue: Original amount in minor units.
        • authorisedAmountValue: 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 URL-encoded blob.

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

    Pre-authorisation response
    {
        "SaleToPOIResponse": {
            "PaymentResponse": {
                "POIData":
                    "POITransactionID": {
                        "TimeStamp": "2019-12-04T13:56:26.000Z",
                        "TransactionID": "8ha5001575467786000.8815754678001083"
                       }
                    {...},
                "SaleData": {...},
                "PaymentReceipt": [...],
                "PaymentResult": {
                    "AuthenticationMethod": [...],
                    "OnlineFlag": true,
                    "PaymentAcquirerData": {...},
                    "PaymentInstrumentData": {...},
                    "AmountsResp": {
                        "AuthorizedAmount": 150.00,
                        "Currency": "EUR"
                    }
                },
                "Response": {
                    "Result": "Success",
                    "AdditionalResponse": "...adjustAuthorisationData=BQABAQA+fbc==..."
                }
            },
            "MessageHeader": {...}
        }
    }
  2. Store the pspReference from the AdditionalResponse for later use when adjusting the authorisation or capturing the payment.
  3. If you're using synchronous authorisation adjustment, also URL decode the adjustAuthorisationData blob and store it.

Step 3 (Optional): Adjust the pre-authorisation

To modify the pre-authorised amount, make an authorisation adjustment request.

  1. Make a POST request to the /adjustAuthorisation endpoint, specifying:

    • originalReference: The pspReference of the pre-authorisation request. You received this in the response to your pre-authorisation request.
    • modificationAmount: The currency and value of the new amount in minor units. This is the sum of the pre-authorised amount and the additional amount. If this is not the first authorisation adjustment, it's the sum of the pre-authorised amount plus all additional amounts.
    • reference: Your reference to this payment modification, for use in your reconciliation process.
    • additionalData.industryUsage: DelayedCharge
    • merchantAccount: The name of your merchant account that is used to process the payment.

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

    Asynchronous authorisation adjustment request
    {
        "originalReference":"8815754678001083",
        "modificationAmount": {
            "currency":"EUR",
            "value":21415
        },
        "reference":"YOUR_MODIFICATION_REFERENCE",
        "additionalData":{
            "industryUsage":"DelayedCharge"
        },
        "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
    }

    The /adjustAuthorisation response contains: 

    • pspReference: The PSP reference associated with this /adjustAuthorisation request. Note that this is different from the PSP reference associated with the pre-authorisation request.
    • response: [adjustAuthorisation-received]
    Asynchronous authorisation adjustment response
    {
      "pspReference": "881576235454101H",
      "response": "[adjustAuthorisation-received]"
    }
  2. Wait for the asynchronous notification. This informs you whether the new amount has been authorised.
  • Make a POST request to the /adjustAuthorisation endpoint, specifying:

    • originalReference: The pspReference of the pre-authorisation request. You received this in the response to your pre-authorisation request.
    • modificationAmount: The currency and value of the new amount in minor units. This is the sum of the pre-authorised amount and the additional amount. If this is not the first authorisation adjustment, it's the sum of the pre-authorised amount plus all additional amounts.
    • reference: Your reference to this payment modification, for use in your reconciliation process.
    • additionalData.adjustAuthorisationData: The previous adjustAuthorisationData blob, in URL-decoded format. For the first adjustment, that's the blob you received in the response to the pre-authorisation request. For the second adjustment, it's the blob you received in the response to the first adjustment, and so on.

      Always use the latest blob.

    • merchantAccount: The name of your merchant account that is used to process the payment.

    The following examples shows how you would add a charge of 64.15 EUR to a pre-authorised amount of 150.00 EUR.

    Synchronous authorisation adjustment request
    {
        "originalReference":"8815754678001083",
        "modificationAmount": {
            "currency":"EUR",
            "value":21415
        },
        "reference":"YOUR_MODIFICATION_REFERENCE",
        "additionalData":{
            "adjustAuthorisationData":"BQABAQA+fbc==..."
        },
        "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
    }

    The /adjustAuthorisation response contains: 

    • additionalData.adjustAuthorisationData: The new blob, for the new authorised amount.
    • merchantReference: Your reference to this payment modification, for use in your reconciliation process.
    • pspReference: The PSP reference associated with this /adjustAuthorisation request. Note that this is different from the PSP reference associated with the pre-authorisation request.
    • response: Authorised. Indicates the new amount is authorised.
    Synchronous authorisation adjustment response
    {
        "additionalData": {
            "adjustAuthorisationData": "BQABAQArqht7L...",
            "merchantReference": "YOUR_MODIFICATION_REFERENCE"
        },
        "pspReference": "8535762347980628",
        "response": "Authorised"
    }
  • URL-decode and store the adjustAuthorisationData blob you received in the /adjustAuthorisation response. You will need this if you later adjust the authorisation again.
  • Step 4: 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:

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

    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 Step 3).

      • 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 /cancel request specifying the pspReference of the original pre-authorisation. Refer to Cancel authorisation for more details.

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

      • originalReference: The pspReference of the original pre-authorisation. You received this in the response to your pre-authorisation request.
      • modificationAmount: 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.
      Capture request
      {
          "originalReference":"8815754678001083",
          "modificationAmount":{
              "currency":"EUR",
              "value":21415
          },
          "reference":"YOUR_MODIFICATION_REFERENCE",
          "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
      }
    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.
      • response: [capture-received].
      • additionalData.merchantReference: Your reference to this payment modification, for use in your reconciliation process.
      Capture response
      {
          "additionalData": {
              "merchantReference": "YOUR_MODIFICATION_REFERENCE"
          },
          "pspReference": "8815762358979809",
          "response": "[capture-received]"
      }
    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.

    If you need to charge the guest for an additional amount after they have left, and you created a shopper recognition token with your pre-authorisation request, you can apply these late charges in a normal payment request using the token. See Shopper recognition.

    See also