kepa
Transactions/createSale

Create a Sale

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

POST/v1/transaction/sale
POST to this endpoint to start an orchestrated sale. The single REST call is blocking — it does not return until the terminal has finished the entire transaction lifecycle: prompting for card presentation, reading the chip, performing CVM (PIN, signature, or no-CVM), running online authorization to the acquirer over ISO 8583, processing second-generate AC, and producing a final result. Expect the call to take roughly 5–15 seconds depending on cardholder interaction and acquirer response time. For live UI updates while the sale is in flight, open a WebSocket session in parallel and consume the same lifecycle events the terminal emits internally.
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.

merchantNamestring

Merchant trading name.

Example: "Atlas Coffee"
merchantIdstring

Acquirer-assigned merchant identifier (MID).

Example: "MID123456789"
terminalIdstring

Acquirer-assigned terminal identifier (TID).

Example: "TID-00012345"
transactionIdstring

Transaction identifier.

dateTimestring · ISO 8601

Local date and time of the transaction.

cardSchemestring

Card scheme name for the receipt (e.g. 'VISA').

maskedPanstring

Masked PAN for receipt display (last 4 only).

Example: "************1234"
applicationLabelstring

EMV application label (e.g. 'Visa Credit').

Example: "Visa Credit"
aidstring

EMV Application Identifier.

Example: "A0000000031010"
authorizationCodestring

Issuer authorization code.

amountinteger

Transaction amount in minor units.

Example: 2500
tipAmountinteger

Tip amount in minor units.

Example: 0
totalAmountinteger

Total amount (amount + tip) in minor units.

Example: 2500
entryModestring

Card entry mode (CONTACTLESS, CONTACT, etc.).

cvmPerformedenum

Cardholder verification method used.

PINSIGNATURECDCVMNO_CVMFAILED
approvalStatusenum

APPROVED or DECLINED.

APPROVEDDECLINED
chipDataobject

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

emvTagsobject

Map of EMV tag hex identifiers to hex-encoded values. Common tags: 9F26 (Application Cryptogram), 9F27 (Cryptogram Info Data), 9F10 (Issuer Application Data), 9F37 (Unpredictable Number), 9F36 (ATC), 9C (Transaction Type), 9F02 (Amount Authorized), 5F2A (Transaction Currency Code), 9A (Transaction Date), 9F1A (Terminal Country Code).

encryptedPinBlockstringnullable

Encrypted PIN block (hex), or null if PIN was not entered.

pinKsnstringnullable

Key Serial Number for the PIN encryption key (hex).

pinBlockFormatenumnullable

PIN block format identifier.

ISO_0ISO_1ISO_3ISO_4
metadataobject

Arbitrary key-value metadata echoed from the request.

commerce-api/openapi.yaml · createSale

POSTLocal
http://terminal:8443/v1/transaction/sale
Request
curl http://terminal:8443/v1/transaction/sale \
  -H "X-Api-Key: $ATLAS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type": "SALE","amount": 2500,"currency": "NZD","entryMode": "AUTO","referenceId": "POS-INV-20260328-001","tipAmount": 0,"metadata": { "cashier": "Jane", "register": "REG-02" }}'
Response
{
  "transactionId": "txn_01JQXYZ123456",
  "status": "APPROVED",
  "type": "SALE",
  "amount": 2500,
  "currency": "NZD",
  "tipAmount": 0,
  "authorizationCode": "A12345",
  "responseCode": "00",
  "cardScheme": "VISA",
  "maskedPan": "************1234",
  "entryMode": "CONTACTLESS",
  "aid": "A0000000031010",
  "applicationLabel": "Visa Credit",
  "cryptogramType": "TC",
  "tvr": "0000000000",
  "cvmResult": "NO_CVM",
  "referenceId": "POS-INV-20260328-001",
  "rrn": "262803141422",
  "timestamp": "2026-03-28T09:14:22Z",
  "receiptData": {
    "merchantName": "Atlas Coffee",
    "merchantId": "MID123456789",
    "terminalId": "TID-00012345",
    "transactionId": "txn_01JQXYZ123456",
    "dateTime": "2026-03-28T09:14:22Z",
    "cardScheme": "VISA",
    "maskedPan": "************1234",
    "applicationLabel": "Visa Credit",
    "aid": "A0000000031010",
    "authorizationCode": "A12345",
    "amount": 2500,
    "tipAmount": 0,
    "totalAmount": 2500,
    "entryMode": "CONTACTLESS",
    "cvmPerformed": "NO_CVM",
    "approvalStatus": "APPROVED"
  },
  "metadata": {
    "cashier": "Jane",
    "register": "REG-02"
  }
}