Pre-authorisation

Introduction

Pre-authorisation is often used by hotels to reserve money for if there are any additional charges the customer must pay after their visit.

Here's an example: a customer arrives at the hotel and the merchant makes a pre-auth of $200 on the customer's card. Now this $200 cannot be spent by the customer, but it is also not transferred to the merchant.

Before the customer leaves the hotel, the merchant completes the pre-auth with a $40 amount. $40 is sent to the merchant, and the remaining $160 is released back to the customer.

Using pre-auths

After opening a pre-auth on a customer's card, there are several actions the merchant can take.

• Get the pre-auth
• Change the pre-auth:
  • Top-up — increase the reserved funds.
  • Partially cancel — decrease the reserved funds.
  • Extend — extend the expiry time.
• Close the pre-auth:
  • Cancel — release all funds to the customer.
  • Complete — transfer an amount of funds to the merchant and release any remaining funds to the customer.
  • Otherwise, the pre-auth will expire after a period of time (usually around two weeks) and transfer all funds to the merchant. The period of time is determined by the customer's card.

Or, instead of using a pre-auth, the merchant can use the verify account action.

📘

Some pre-auth actions are not supported by all customer cards.

Open pre-auth

To open a pre-auth on a customer's card, call POST /v1/pre_auth/open

In the request, take note of the following.

• posRefId — since each pre-auth action is a separate transaction, each needs its own unique 'posRefId'.
• preAuthAmount — the amount of funds to reserve.

In the response, take note of the following.

• preauth_id — a unique string that identifies the open pre-auth transaction. Store this in your POS because you will need it later to edit or close the pre-auth transaction.
• preauth_amount — the amount of funds reserved.

Get pre-auth

To get the details of a pre-auth, call GET /v1/pre_auth with the posRefId of the latest action that was made to the pre-auth.

For example, if you open the pre-auth using a posRefId of "aa2bc19f..." and you top it up using a posRefId of "bb3c5372...", you would get the pre-auth using http://localhost:8282/v1/pre_auth?posRefId=bb3c5372...

Top up pre-auth

To increase the amount of reserved funds in a pre-auth, call POST /v1/pre_auth/topup

For example, if a customer's card has a pre-auth of $200 and you add a top-up of $100, it will then be $300 in total.

In the request, take note of the following.

• posRefId — since each pre-auth action is a separate transaction, this must be different from the posRefId that you used when opening the pre-auth.
• preAuthId — enter the preauth_id that was returned after you opened the pre-auth.
• preAuthAmount — the amount of funds to add to the pre-auth.

In the response, take note of the following.

• preauth_amount — the original amount of the pre-auth, before any top-ups were made.
• existing_preauth_amount — the amount of the pre-auth before this top-up was added.
• topup_amount — the amount of this top-up.
• balance_amount — the current total amount of the pre-auth.

Partially cancel pre-auth

To decrease the amount of reserved funds in a pre-auth by releasing some to the customer, call POST /v1/pre_auth/partial_cancellation

This will not close the pre-auth, and it cannot be used to decrease the amount to zero. (To close the pre-auth, you will need to cancel or complete it instead.)

In the request, the preAuthAmount is the amount of funds to release from the pre-auth.

In the response, the preauth_cancel_amount is the amount of funds released. The existing_preauth_amount and balance_amount are as described above.

Extend pre-auth

To extend the time until a pre-auth expires, call POST /v1/pre_auth/extend

This will extend the time of expiry by around two weeks, depending on the customer's card.

Cancel pre-auth

To cancel a pre-auth, call POST /v1/pre_auth/cancellation

This will release all of the reserved funds back to the customer and close the pre-auth.

Complete pre-auth

To complete a pre-auth, call POST /v1/pre_auth/complete

This will transfer an amount of funds to the merchant, release any remaining funds to the customer, and close the pre-auth.

In the request, take note of the following.

• preAuthAmount — the amount of funds to transfer to the merchant. This can be less than, equal to, or more than the amount of the pre-auth.
  • Less than the pre-auth — the remaining funds are released to the customer.
  • Equal to the pre-auth — the full pre-auth amount is transferred to the merchant.
  • More than the pre-auth — the pre-auth completion amount will be validated during the transaction and if it is more then the pre-auth open amount then it will be unsuccessful.
• surchargeAmount — a surcharge can be added to the amount transferred to the merchant.

Verify account

To verify that a customer's credit card is valid, call POST /v1/pre_auth/account_verify

Merchants sometimes use this instead of a pre-auth — they verify the customer's card and then hold the card until the customer pays.