Pre-authorisation and Capture

Overview

Pre-authorisation is an initial authorisation transaction that reserves funds on a card for a sale to be processed at a later time. The funds are not debited from the cardholders account until the final payment (capture) is processed. This is useful for scenarios where you want to ensure that the customer has sufficient funds before capturing a transaction, such as in hotel bookings or car rentals.

Pre-authorisation can be performed using the following methods:

• OnlinePay Checkout (Hosted Payment Page or iFrame)
• Payment links created using the OnlinePay Checkout API
• Shopping cart plugins
• eCommerce API

Pre-authorisation and Capture Process

Merchants can configure the above payment methods to perform pre-authorisation and capture transactions. The process typically involves the following steps:

1. Pre-authorisation: The merchant initiates a pre-authorisation transaction, which places a hold on the customer's funds. This is done by sending a request to the payment gateway with the necessary transaction details, such as the amount and card information.
2. Capture: Once the merchant is ready to complete the transaction, they can capture the funds through their OnlinePay dashboard or API. This involves sending a request to the payment gateway to transfer the held funds from the customer's account to the merchant's account.

When a pre-authorisation payment is made, the funds are reserved on the cardholder's account but not yet captured by the merchant. For example, if a customer makes a purchase through a merchant's website where the payment type has been configured as PreAuth instead of Sale, the payment will be held as pre-authorised on their account to ensure that the customer has sufficient funds before completing the transaction, or hold the funds while the order is being processed.

How long does a pre-authorisation last?

The pre-authorisation hold typically lasts for a limited period, usually between 7 to 30 days, depending on the card issuer and the payment gateway. The amount of time before the hold expires can vary based on the card issuer and the merchant category. For example, certain industries, such as hotels, motels, resorts, and car rentals, may have longer pre-authorisation periods due to the nature of their services. After the pre-authorisation period has expired, if the merchant has not captured the funds, the hold will be released, and the funds will be returned to the customer's account. Merchants should ensure that they capture the funds within the specified time frame to avoid losing the pre-authorisation hold.

Capturing a pre-authorisation

Merchants can capture a pre-authorisation through their OnlinePay dashboard or API. Capturing a pre-authorisation finalises the transaction and transfers the held funds from the customer's account to the merchant's account. This is typically done when the merchant is ready to complete the sale, such as when the goods are shipped or the service is provided.

To capture a pre-authorisation through the OnlinePay dashboard, follow these steps:

1. Log in to your OnlinePay dashboard.
2. Navigate to Commerce > Reporting > Orders/Transactions.
3. Locate the pre-authorisation transaction you want to capture, and click on it to view the transaction details.
   
4. In the Actions tab, select Capture.
5. Enter the amount you want to capture (if different from the original pre-authorisation amount), then click Capture.
   

The Actions tab will now show the transaction as captured. The only further action available is to refund the transaction. The transaction will be marked as Capture in the Type column of the transaction list.

ℹ️

For more information about transaction types and states, see Transaction Types and States.

Extend a pre-authorisation

Pre-authorisations can be extended through the OnlinePay dashboard or eCommerce API depending on the card issuer's approval.

To extend a pre-authorisation, follow these steps:

1. In your OnlinePay dashboard, navigate to Commerce > Reporting > Orders/Transactions.
2. Locate the pre-authorisation transaction you want to extend, and click on it to view the transaction details.
3. In the Actions tab, select Extend.
4. Click Extend.

The transaction will be marked as Extend in the Type column of the transaction list.

Cancel pre-authorisation

If you need to cancel a pre-authorisation before the expiration date, you can do so through the OnlinePay dashboard or via the eCommerce API. This may be necessary if the customer cancels their order or if the pre-authorisation is no longer needed.

Cancelling a pre-authorisation will release the hold on the funds, allowing the customer to access their money again. The funds will be returned to the customer's account, and the pre-authorisation will be marked as Void in the transaction list. This cannot be undone, and the pre-authorisation will no longer be valid.

Cancel a pre-authorisation through the OnlinePay dashboard

1. In your OnlinePay dashboard, navigate to Commerce > Reporting > Orders/Transactions.
2. Locate the pre-authorisation transaction you want to cancel, and click on it to view the transaction details.
3. In the Actions tab, select Cancel.
   
4. Click Cancel transaction to confirm the cancellation of the pre-authorisation.

When the pre-authorisation is cancelled, the transaction Type will appear as Void in the Orders/Transactions list, but the State will remain as Authorised. The funds will be returned to the customer's account, and the pre-authorisation will no longer be valid.

Cancel a pre-authorisation through the eCommerce API

To void or cancel a pre-authorisation through the eCommerce API Void endpoint. This will cancel the pre-authorisation and release the hold on the funds. The pre-authorisation will be marked as Void in the transaction list.

To cancel a pre-authorisation through the eCommerce API, send a POST request to the /transactions/{id}/void endpoint. The {id} parameter should be replaced with the ID of the pre-authorisation transaction you want to cancel.

Retrieve the transaction ID from the OnlinePay dashboard

The required transaction ID can be found in the Orders/Transactions list in your OnlinePay dashboard, or in the response body of an API request that created the pre-authorisation.

Retrieve the transaction ID from the API and use it to cancel the pre-authorisation

You can also use the GET request to retrieve the transaction details and find the ID of the pre-authorisation transaction you want to cancel. The GET Transactions endpoint will return a list of all transactions, including pre-authorisations, with their corresponding IDs. You can filter the list by appending the GET request with the ?type=preauth query parameter to only return pre-authorisation transactions.

For example, to retrieve a list of pre-authorisation transactions with a limit of the last 50 matches, you can use the following request:

curl --request GET \
     --url 'https://au.gsc.verifone.cloud/oidc/api/v2/transactions?transaction_type=PREAUTH&_limit=50' \
     --header 'accept: application/json'

The response will include a list of pre-authorisation transactions with their corresponding IDs in the id field. You can then use the ID of the pre-authorisation transaction you want to cancel in the POST request to the /transactions/{id}/void endpoint.