Terminal API/recordTerminalOfflineCompletion

Record an offline terminal decision

POST/api/v1/terminal/transactions/offline-complete

Records a kernel-approved or declined offline transaction. This route rejects PAN, Track 2 and PIN material and accepts only allowlisted non-sensitive EMV tags. It is not deferred authorization; later host authorization is a separate flow.

Request body

application/json

deviceIdstringRequired

Example "dev_01JQXYZ123456"

paymentSessionIdstring

Remote terminal command session. The device must echo this value so the host validates amount, currency, operation, and ownership before authorization.

terminalIdstringRequired

Example "TID-00012345"

amountintegerRequired

Example 2500

baseAmountMinorinteger

Subtotal before tip. When supplied, base plus tip must equal amount.

Example 2200

tipAmountMinorinteger

Tip collected before authorization.

Example 300

tipSourcestring

Terminal selection source such as preset:1800, fixed:100, custom, or none.

Example "preset:1800"

currencyCodestringRequired

Example "USD"

transactionTypeenum

purchasepre_authrefund

Example "purchase"

originalTransactionIdstring

Required for a refund.

Example "0195d46e-7088-7cc4-a9b2-5f9273cd63b8"

entryModestringRequired

Example "Chip"

completionModestring

Device/kernel completion contract selected for this acceptance mode.

Example "CONTACT_CHIP_SECOND_AC"

railIdstring

Example "rail_01JQXYZ123456"

vendorstring

Example "PAX"

acceptanceModestring

Example "CONTACT"

cardSchemestring

Example "VISA"

maskedPanstring

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

applicationPanstring

Clear EMV tag 5A used only for the synchronous authorization. Mutually exclusive with panEncrypted; never log or persist.

Example "<ephemeral-application-pan>"

panEncryptedstring

Device-encrypted PAN ciphertext. Mutually exclusive with clear applicationPan and track2; never log or persist outside the approved CHD boundary.

Example "<device-encrypted-account-data>"

accountDataKsnstring

KSN for panEncrypted. This is not the PIN KSN.

Example "FFFF9876543210E00001"

accountDataKeySchemeenum

TDES_DUKPTAES_DUKPT

Example "TDES_DUKPT"

track2string

Clear ephemeral Track 2. Mutually exclusive with panEncrypted; never log or persist.

Example "<ephemeral-track2>"

emvTlvobject

cryptogramstring

Example "1122334455667788"

cidstring

Example "80"

atcstring

Example "0012"

tvrstring

Example "0000000000"

iadstring

Example "06010A03A02000"

unpredictableNumberstring

Example "A1B2C3D4"

cvmstring

Example "ONLINE_PIN"

pinBlockstring

Device-encrypted PIN block; never log. Requires the separate PIN ksn.

Example "<device-encrypted-pin-block>"

ksnstring

PIN-encryption KSN. This is not accountDataKsn.

Example "FFFF9876543210E10001"

pinBlockFormatstring

Example "ISO_0"

pinKeySchemestring

Example "DUKPT_TDES"

metadataobject

Response

application/json

idstringRequired

Stable payment identifier. Payment IDs use the engine's UUID identifier format across every acceptance channel.

Example "0195d46e-7088-7cc4-a9b2-5f9273cd63b8"

merchantIdstringRequired

Owning merchant. Required on every payment: one engine needs one tenancy root, stated rather than implied by the credential used.

Example "mch_123"

acceptanceChannelenumRequired

How the payment was accepted. `EXTERNAL_RAIL` covers sales authorized by a pre-certified terminal app on someone else's rail. kepa records them for reporting and never enters their authorization loop, so they carry no kepa authorization state.

CARD_PRESENTCARD_NOT_PRESENTEXTERNAL_RAIL

statusenumRequired

Where the payment is in its lifecycle. This reconciles two previously separate machines: card-present was terminal-outcome-shaped (`APPROVED`, `REVERSED`) and online was intent-lifecycle-shaped (`REQUIRES_CONFIRMATION`, `SUCCEEDED`). They shared exactly one member. `REQUIRES_CAPTURE` covers both an online uncaptured authorization and a terminal pre-auth awaiting completion: both are authorized, holding funds, and waiting on a second message. Use `type` to tell them apart. `FAILED` means the outcome is unknown, not that no money moved — a payment that failed in flight may still be reversed.

REQUIRES_PAYMENT_METHODREQUIRES_CONFIRMATIONREQUIRES_ACTIONPROCESSINGREQUIRES_CAPTURESUCCEEDEDDECLINEDREVERSEDCANCELEDFAILED

typeenumRequired

What kind of movement this is. A completed pre-authorization stays `PRE_AUTH` — completing it moves the same payment from `REQUIRES_CAPTURE` to `SUCCEEDED` rather than creating a second record. There is no `PRE_AUTH_COMPLETE` type: completion is an operation, not a state a payment can be in.

SALEPRE_AUTHREFUNDVOIDCARD_READBALANCE_INQUIRY

captureMethodenum

`AUTOMATIC` captures on approval. `MANUAL` holds the authorization open for a later capture, and is what distinguishes a completed pre-authorization from a straight sale once both are captured.

AUTOMATICMANUAL

capturedAmountMinorintegernullable

What was actually captured, which may be less than `amountMinor` — a tip adjusted down, a partial fulfilment. Null until capture, so an authorization awaiting capture is distinguishable from one captured for zero.

authExpiresAtstring · ISO 8601nullable

When the issuer's hold lapses. An expired authorization cannot be captured: the funds are no longer reserved.

Example "2026-04-09T09:14:22Z"

amountMinorintegerRequired

Amount in the currency's minor unit — 2500 is NZD 25.00. Named `amountMinor`, not `amount`, because the unit is the field most likely to cause a money bug and the name should carry it.

Example 2500

baseAmountMinorintegerRequired

Subtotal before the tip, in minor units.

Example 2200

currencyCodestringRequired

ISO 4217 currency code.

Example "NZD"

tipAmountMinorintegerRequired

Tip in minor units, where the channel supports it.

Example 0

tipSourcestringnullable

How the terminal collected the tip, such as `preset:1800`, `fixed:100`, `custom`, or `none`.

Example "preset:1800"

cashbackAmountMinorinteger

Cashback in minor units, card-present only.

customerIdstring

Customer this payment belongs to, when one is attached.

Example "cus_123"

referenceIdstring

Caller-assigned reference, echoed back on every read.

Example "POS-INV-20260328-001"

authorizationCodestring

Issuer authorization code.

Example "A12345"

responseCodestring

ISO 8583 response code. `"00"` is approved.

Example "00"

cardSchemeenum

VISAMASTERCARDAMEXDISCOVERJCBUNIONPAYEFTPOSOTHER

Example "VISA"

maskedPanstring

Masked account number. Never more than the first six and last four digits; the engine drops any value revealing more.

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

rrnstring

Retrieval reference number.

Example "262803141422"

declineobject

Why a payment did not succeed, and what to do about it. The engine already computes this taxonomy to drive its own retry and cascade decisions; this exposes it rather than adding new behaviour. It is what makes "retries are automatic" legible to an integrator.

cardPresentobject

Present when `acceptanceChannel` is `CARD_PRESENT`.

cardNotPresentobject

Present when `acceptanceChannel` is `CARD_NOT_PRESENT`.

settlementIdstringnullable

Settlement batch this payment was funded in, once settled.

Example "stl_01JQDAY00042"

metadataobject

Caller-supplied key/value metadata. Max 20 keys, 256 characters per value.

createdAtstring · ISO 8601Required

Example "2026-04-09T09:14:22Z"

updatedAtstring · ISO 8601

Example "2026-04-09T09:14:22Z"

recordTerminalOfflineCompletion