kepa
Transactions/createSale

Create a Sale

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.

Kick off a full sale on the terminal in one call.

POST/v1/terminal/sale
Run a full sale on the terminal in one blocking call — card prompt, chip read, CVM, online authorization, and second-generate AC. It returns when the transaction reaches a terminal state, typically 5–15 seconds. For a live cardholder UI, open a WebSocket session in parallel and consume the same lifecycle events.
Sale lifecycle
~5–15 seconds
What happens after a single POST /v1/transaction/sale. Each step is also emitted as a WebSocket event if you connect a session in parallel.
POS sends salePOST /transaction/sale01Readywaiting_for_card02Tap detectedcard_detected03Authorizingprocessing04Approvedresult05

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.

Good to know
  • This is a blocking call. Set a generous client-side timeout (we recommend 90s).
  • Use the WebSocket session in parallel if you want to drive a live cardholder UI.
  • The terminal returns 409 if another transaction is already in progress — abort or wait, then retry.

createSale