Pre-authorize a payment

Pre-authorizing a payment lets you increase or decrease the authorized amount at later stages. Such changes to a pre-authorized payment are called authorization adjustments. After you make your final authorization adjustment, you need to manually capture the payment.

This payment flow is customary, for example in:

• Hospitality where the hotel pre-authorizes payment for the room that the guest booked, and adjusts that authorization with the guest's expenses at the hotel facilities.
• In-person tipping where guests add a tip on the receipt after they have presented their card.
• Pre-ordering items online.

When you consider implementing pre-authorization and 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.
• Expiration: pre-authorizations and authorizations expire after a while, depending on the card scheme. Ideally, you capture the payment before the pre-authorization expires.

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 do not 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.

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.

Configure your account (Optional)

To receive the initial adjustAuthorisationData blob in the pre-authorization response and to subsequently receive the authorization adjustment results synchronously, ask our Support Team to enable this.

Step 1: Pre-authorize a payment

To start the pre-authorization flow:

1. Make an authorization request by sending a POST request to the /hosttohostpaymentgateway/v#/payments endpoint with:

   • authorisationType: PreAuth

   The following example shows a pre-authorization request for EUR 150.

2. When you receive the response, note the following:

   Field	Description
   adjustAuthorisationData	A blob with authorization data. Save this if you want to use synchronous authorization adjustment. Only included if enabled by our Support Team.
   pspReference	Our unique identifier for the request. Save this, because you need it for the completion request, for asynchronous authorization adjustments (if not using synchronous adjustment), and for the final manual capture request.

3. Make a completion request by sending a POST request to the /hosttohostpaymentgateway/v#/payments/{paymentPspsReference}/completions endpoint. In the URL, {paymentPspReference} is the pspReference of the authorization response.

   If the default capture method for your account is not manual, set captureDelay to manual in your completion request.

Step 2 (optional): Adjust the pre-authorized amount

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

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.

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 of the authorization response.

2. When you are ready to capture the payment, make a manual capture request by sending a POST /payments/{paymentPspReference}/captures request, where {paymentPspReference} is the PSP reference of the authorization response.

See also