Transactions/createPreAuth

Pre-authorize Funds

Planned

Planned. This contract is published ahead of the build. It is not callable yet — treat it as the shape to design against, not a live endpoint.

Reserve funds now, capture them later.

POST/v1/terminal/pre-auth

Reserve funds on the card now and capture them later. Complete or void every pre-auth — the issuer's hold expires on its own after a few days if you don't, so capture before then. For hotels, car rental, fuel, and any flow where the final amount isn't known at the terminal.

Request body

application/json

typeenumRequired

Transaction type.

SALEPRE_AUTHPRE_AUTH_COMPLETEREFUNDVOIDCARD_READBALANCE_INQUIRY

Example "SALE"

amountintegerRequired

Transaction amount in minor units. For a $25.00 NZD transaction, send 2500. Use 0 for card-read and balance-inquiry.

Example 2500

currencystringRequired

ISO 4217 currency code.

Example "NZD"

cashbackAmountinteger

Cashback amount in minor units (sale transactions only).

Example 0

entryModeenum

Card entry mode preference. AUTO lets the terminal accept any method.

CONTACTLESSCONTACTAUTO

Example "AUTO"

referenceIdstring

POS-assigned reference identifier for this transaction (max 64 chars).

Example "POS-INV-20260328-001"

originalTransactionIdstring

Required for refund, void, and pre-auth completion. The transactionId of the original transaction being referenced.

tipAmountinteger

Tip amount in minor units.

Example 0

metadataobject

Arbitrary string key-value metadata attached to the transaction. Echoed in the response and available in reconciliation exports. Max 20 keys, 256 chars per value.

Response

application/json

transactionIdstringRequired

Unique identifier for this transaction.

Example "txn_01JQXYZ123456"

statusenumRequired

Terminal or in-flight state of the transaction.

APPROVEDDECLINEDCANCELLEDERRORREVERSEDPENDING_ONLINEPENDING_COMPLETION

typeenumRequired

Transaction type (echoed from the request).

SALEPRE_AUTHPRE_AUTH_COMPLETEREFUNDVOIDCARD_READBALANCE_INQUIRY

amountintegerRequired

Transaction amount in minor units.

Example 2500

currencystringRequired

ISO 4217 currency code.

Example "NZD"

tipAmountinteger

Tip amount in minor units.

Example 0

authorizationCodestring

Authorization code from the issuer.

Example "A12345"

responseCodestring

ISO 8583 response code. "00" = approved.

Example "00"

cardSchemeenum

Card scheme / network.

VISAMASTERCARDAMEXDISCOVERJCBUNIONPAYEFTPOSOTHER

maskedPanstring

Masked primary account number. Only the last 4 digits are visible; all other positions are replaced with asterisks.

Example "************1234"

entryModeenum

Actual card entry mode used.

CONTACTLESSCONTACTMAGSTRIPEMANUAL

aidstring

EMV Application Identifier (AID) hex string.

Example "A0000000031010"

applicationLabelstring

EMV application label.

Example "Visa Credit"

cryptogramTypeenum

Type of cryptogram generated by the card. TC = Transaction Certificate (offline approved), ARQC = online auth required, AAC = declined.

TCARQCAAC

tvrstring

Terminal Verification Results (10-character hex).

Example "0000000000"

cvmResultenum

Cardholder Verification Method used.

PINSIGNATURECDCVMNO_CVMFAILED

referenceIdstring

POS-assigned reference identifier (echoed).

rrnstring

Retrieval Reference Number.

Example "262803141422"

timestampstring · ISO 8601Required

Transaction timestamp (ISO 8601).

Example "2026-03-28T09:14:22Z"

receiptDataobject

Structured receipt data for rendering cardholder and merchant receipts. See the Receipt Requirements page for rendering rules.

chipDataobject

EMV chip data for POS-side acquirer routing. Only populated in granular mode (status = PENDING_ONLINE).

metadataobject

Arbitrary key-value metadata echoed from the request.

createPreAuth