Preauthorisation

Introduction

Preauthorisations 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 preauthorisation flow using our Payments API covering:

Initial preauthorisation
Preauthorisation amount adjustment (we will be incrementing here)
Preauthorisation completion

1. Initial Preauthorisation

To create an initial preauthorisation, 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. Preauthorisation adjustment

In order to either increment or decrement an existing preauthorisation, 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": "YxsaGW@nzVTEnXyyUBgQkwAAA2g",
  "ipgTransactionId": "84607420067",
  "orderId": "R-fc6d3983-9d33-4cc8-8c49-c6ca1f92c14f",
  "transactionType": "PREAUTH",
  // ...
  "approvedAmount": {
    "total": 15.99,
    "currency": "EUR",
    "components": {
      "subtotal": 15.99
    }
  },
  // ...
}

3. Preauthorisation completion

In order to finalise or complete the preauthorisation, a request to one of the 'secondary' transaction endpoints must be made. This can be done using the transaction id or the order id). In the below example the /orders/:orderId option, POSTing a PostAuthTransaction requestTypehas been used:

// 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 as complete. If we will try to post another completion to this order ID, we'd see an error response explaining that.