Pre-authorisation
Pre-authorisation (pre-auth) allows merchants to reserve funds on a customer’s card before either charging or releasing the funds later.
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 thepreauth_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 11 months ago