Skip to main content

Process a Pre-Authorization

Use pre-authorization to reserve funds on a customer's card without capturing them immediately. The hold typically lasts 7-30 days depending on the card issuer.

When to Use​

  • Hotel check-ins (final amount unknown until checkout)
  • Car rentals (security deposit)
  • Restaurants (tip added later)
  • Any scenario where the final amount may differ from the initial charge

Prerequisites​

  • Understand EPOS communication
  • A paired terminal with a valid auth token
  • Terminal IP address and serial number

Steps​

  1. Send a pre-authorization request:
curl --location 'https://{IP}:{PORT}/payntpos/1.0.0/transaction?tid={TID}&disablePrinting=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: {AUTH_TOKEN}' \
--data '{
    "transType": "PREAUTH",
    "reference": "reservation-789",
    "amountTrans": 20000
}'
  1. The terminal displays the payment screen.
  2. The customer taps or inserts their card.
  3. The response returns a UTI:
{
    "transType": "PREAUTH",
    "amountTrans": 20000,
    "uti": "c4b0a015-abea-3759-b5d1-dd82d0a7cc26"
}

The UTI is an alphanumeric string consisting of 1-64 characters. Special characters  are not allowed. For example, 000000000001, 000000000002, 000000000003. Each UTI must be a unique value. The UTI can be re-used only when the previous one expires, which currently happens after 3 months, though this is subject to change.

  1. Save the UTI—you'll need it to capture or void the pre-authorization.

Request Parameters​

FieldTypeRequiredDescription
transTypestringYesSet to PREAUTH
amountTransintegerYesAmount to reserve in cents
referencestringNoYour reference ID for tracking. The reference ID is an alphanumeric string consisting of 1-36 characters, Special characters are not allowed. Usually shown in 5 groups separated by hyphens, for example, gr3d4fae-9dec-11d0-a763-00a0c91e6bf1.

What Happens Next​

After a pre-authorization, you have two options:

  1. Capture the funds – Use How to Capture a Pre-Authorization to finalize the charge.
  2. Void the pre-authorization – Use How to Void a Transaction to release the hold.

If you take no action, the hold expires automatically (typically 7-30 days).

Important Notes​

  • The reserved amount is not yet charged—it's only a hold on the customer's available credit.
  • You can capture less than the pre-authorized amount (partial capture).
  • You cannot capture more than the pre-authorized amount.