Transactions/createCardRead

Read Card Only

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.

Tokenize or identify a card without charging it.

POST/v1/terminal/card-read

Read a card without creating a Payment or moving funds. Returns only a masked display value and terminal metadata. Full PAN, Track 2, cryptograms, PIN data, and raw EMV tags never cross this boundary. Tokenization requires a separate vault-backed flow.

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

operationIdstringRequired

Ephemeral terminal operation ID; never a payment ID.

cardSchemestring

Detected card scheme.

maskedPanstring

Masked display value only.

entryModeenum

How the card was presented.

aidstring

Selected application identifier.

applicationLabelstring

Selected application label.

referenceIdstring

Caller reference copied from the request.

readAtstring · ISO 8601Required

When the terminal completed the read.

createCardRead