7. Pre-authorisation

Pre-authorisation reserves funds now and captures them later — the hotel and fuel pattern. It is a conditional capability: build it only if pre-auth is in your contract scope, and expect certification to include it only then. The lifecycle has three verbs: open, complete, cancel.

Open — FirstReservation

A standard payment with PaymentType: "FirstReservation":

"PaymentRequest": {
  "PaymentData": {"PaymentType": "FirstReservation"},
  "PaymentTransaction": {"AmountsReq": {"Currency": "EUR", "RequestedAmount": "11.99"}},
  "SaleData": {"OperatorID": "Cashier_01", "SaleTransactionID": {"TimeStamp": "...", "TransactionID": "3001"}}
}

The response is a normal PaymentResponse. Store two things: the POITransactionID and the SaleReferenceID — the completion needs the reference.

Complete — Completion

To capture, send PaymentType: "Completion" with the SaleReferenceID from the original reservation in SaleData, and the amount to capture:

"PaymentRequest": {
  "PaymentData": {"PaymentType": "Completion"},
  "PaymentTransaction": {"AmountsReq": {"Currency": "EUR", "RequestedAmount": "11.99"}},
  "SaleData": {"OperatorID": "Cashier_01", "SaleReferenceID": "19", "SaleTransactionID": {"TimeStamp": "...", "TransactionID": "3002"}}
}

The captured amount may be lower than the reserved amount (fuel dispensed less than reserved).

Cancel — via Reversal

Warning

You cannot close a pre-authorisation by completing with amount 0. To release a reservation without capturing, send a Reversal referencing the reservation's POITransactionID.

Bookkeeping rules

  • One reservation → one completion. Track open reservations in your POS and prevent double capture.
  • The reservation and the completion are separate transactions with separate POITransactionIDs; your records need both, linked by the SaleReferenceID.
  • An expired or already-captured reservation fails the completion — surface the terminal's error rather than retrying blind.

Related

  • Taking a payment — PaymentType: Normal sales; this page never applies to them.
  • Reversing a transaction — the cancel mechanism.