Documentation

Pre-authorisation

Pre-authorisation (pre-auth) allows merchants to reserve funds on a customer’s card before either charging or releasing the funds later.

Suggest Edits

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.

Sequence diagram of opening then completing a pre-auth transaction.

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:
  • 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.

Updated about 1 year ago