Pre-authorisation
Introduction
Pre-authorisations are a way for merchants to place an initial hold on funds, then adjusting the amount before actually finalising the transaction at a later date.
A real-world example would be a hotel booking. The hotel may put a hold on the initial booking amount as a pre-authorisation, then adjust the amount during the clients stay (as they put expenses on their room), before 'completing' the transaction when the client checks out.
This gives the merchant some safety, and allows them to bundle up a number of purchases into a single transaction.
Payments API
This section shows a set of example requests / response for a pre-authorisation flow using our Payments API covering:
- Initial pre-authorisation
- Pre-authorisation amount adjustment (we will be incrementing here)
- Pre-authorisation completion
1. Initial Pre-authorisation
To create an initial pre-authorisation, use the Generate Primary Transaction endpoint with the appropriate PreAuth requestType for the payment method, for example:
// POST /payments
{
"requestType": "PaymentCardPreAuthTransaction",
"merchantTransactionId": "Merchant-1234",
"transactionAmount": {
"currency": "EUR",
"total": "11.99"
},
"paymentMethod": {
"paymentCard": {
"number": "1234123412341234",
"securityCode": "007",
"expiryDate": {
"month": "01",
"year": "28"
}
}
}
}
{
"clientRequestId": "9e3c43a2-37ee-4974-ae6f-4ff1cd5145fb",
"apiTraceId": "YxsZcYUtIJXwUdM33R3MlgAAA6k",
"ipgTransactionId": "84607419947", // <-- transaction reference
"orderId": "R-fc6d3983-9d33-4cc8-8c49-c6ca1f92c14f", // <-- order reference
"transactionType": "PREAUTH",
// ...
"approvedAmount": {
"total": 11.99,
"currency": "EUR",
"components": {
"subtotal": 11.99
}
},
// ...
}
Note that the response will contain an ipgTransactionId and orderId that can be used in any subsequent calls.
2. Pre-authorisation adjustment
In order to either increment or decrement an existing pre-authorisation, another primary transaction should be made quoting the orderId of the previous transaction and using the same requestType . The transaction amount should be the amount to adjust (increment or decrement). This will send back a similar response, but with an updated amount.
// POST /payments
{
"requestType": "PaymentCardPreAuthTransaction",
"merchantTransactionId": "Merchant-1234",
"transactionAmount": {
"currency": "EUR",
"total": "15.99"
},
"paymentMethod": {
"paymentCard": {
"number": "1234123412341234",
"securityCode": "007",
"expiryDate": {
"month": "01",
"year": "28"
}
}
},
"order": {
"orderId": "R-fc6d3983-9d33-4cc8-8c49-c6ca1f92c14f" // <-- your id here
}
}
{
"clientRequestId": "c359d49a-931a-4756-b8d3-82ae2a1895b6",
"apiTraceId": "[email protected]",
"ipgTransactionId": "84607420067",
"orderId": "R-fc6d3983-9d33-4cc8-8c49-c6ca1f92c14f",
"transactionType": "PREAUTH",
// ...
"approvedAmount": {
"total": 15.99,
"currency": "EUR",
"components": {
"subtotal": 15.99
}
},
// ...
}
3. Pre-authorisation completion
In order to finalise or complete the pre-authorisation, a request to one of the 'secondary' transaction endpoints must be made. This can be done using the transaction id or the order id). Here, we'll be using the /orders/:orderId option, POSTing a PostAuthTransaction requestType:
// POST /orders/R-fc6d3983-9d33-4cc8-8c49-c6ca1f92c14f
{
"requestType": "PostAuthTransaction",
"transactionAmount": {
"total": "15.99",
"currency": "EUR"
}
}
{
"clientRequestId": "9fa587f3-f3ea-46ed-a3a1-f0f94df98fe3",
"apiTraceId": "YxsbbM88SeI78IMF2AP8lAAAA2A",
"ipgTransactionId": "84607420342",
"orderId": "R-fc6d3983-9d33-4cc8-8c49-c6ca1f92c14f",
"transactionType": "POSTAUTH",
// ...
"approvedAmount": {
"total": 15.99,
"currency": "EUR",
"components": {
"subtotal": 15.99
}
},
// ...
}
{
"clientRequestId": "70d0f186-dc17-4dac-bfee-cf5c85a3b6ff",
"apiTraceId": "YxseXIUtIJXwUdM33R3U9QAAA6s",
"responseType": "GatewayDeclined",
"orderId": "R-fc6d3983-9d33-4cc8-8c49-c6ca1f92c14f",
// ...
"error": {
"code": "50292",
"message": "No incremental preauth allowed since it is completed"
}
}
Note that a splitShipment field can be used here where there are multiple shipments against a single original pre-authorisation. Here, this isn't being used.
The response will send back the familiar transaction model with the final status
Example complete!
This transaction is now considered complete, if we tried to post another pre-authorisation to this orderId, we'd see an error response explaining that.
Updated 23 days ago
