Terminal API/authorizeTerminalTransaction

Authorize a terminal transaction

POST/api/v1/terminal/transactions/authorize

Authorize a payment collected by a provisioned Android terminal. The terminal handles the card and PIN and sends encrypted payment data to kepa. Reuse the same Idempotency-Key if the response is lost. When PIN is present, `ksn` identifies the PIN encryption key; `accountDataKsn` identifies the separately encrypted card data. Do not swap them.

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

paymentobjectRequired

emvobjectRequired

transactionIdstringRequired

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

approvedbooleanRequired

Example true

responseCodestringRequired

Example "00"

authorizationCodestring

Example "A12345"

rrnstring

Example "612345678901"

issuerAuthDatastring

Example "3030"

issuerScript71string

issuerScript72string

messagestring

Example "Approved"

authorizeTerminalTransaction

curl https://api.kepapay.co/api/v1/terminal/transactions/authorize \ -H "Authorization: Bearer $KEPA_DEVICE_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "deviceId": "dev_01JQXYZ123456", "paymentSessionId": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8", "terminalId": "TID-00012345", "amount": 2500, "baseAmountMinor": 2200, "tipAmountMinor": 300, "tipSource": "preset:1800", "currencyCode": "USD", "transactionType": "purchase", "originalTransactionId": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8", "entryMode": "Chip", "completionMode": "CONTACT_CHIP_SECOND_AC", "railId": "rail_01JQXYZ123456", "vendor": "PAX", "acceptanceMode": "CONTACT", "cardScheme": "VISA", "maskedPan": "************1234", "applicationPan": "<ephemeral-application-pan>", "panEncrypted": "<device-encrypted-account-data>", "accountDataKsn": "FFFF9876543210E00001", "accountDataKeyScheme": "TDES_DUKPT", "track2": "<ephemeral-track2>", "emvTlv": { "9F26": "1122334455667788", "9F27": "80", "9F36": "0012" }, "cryptogram": "1122334455667788", "cid": "80", "atc": "0012", "tvr": "0000000000", "iad": "06010A03A02000", "unpredictableNumber": "A1B2C3D4", "cvm": "ONLINE_PIN", "pinBlock": "<device-encrypted-pin-block>", "ksn": "FFFF9876543210E10001", "pinBlockFormat": "ISO_0", "pinKeyScheme": "DUKPT_TDES", "metadata": {} }'

{ "payment": { "id": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8", "merchantId": "mch_123", "acceptanceChannel": "CARD_PRESENT", "status": "REQUIRES_PAYMENT_METHOD", "type": "SALE", "captureMethod": "AUTOMATIC", "capturedAmountMinor": 0, "authExpiresAt": "2026-04-09T09:14:22Z", "amountMinor": 2500, "baseAmountMinor": 2200, "currencyCode": "NZD", "tipAmountMinor": 0, "tipSource": "preset:1800", "cashbackAmountMinor": 0, "customerId": "cus_123", "referenceId": "POS-INV-20260328-001", "authorizationCode": "A12345", "responseCode": "00", "cardScheme": "VISA", "maskedPan": "************1234", "rrn": "262803141422", "decline": { "category": "INSUFFICIENT_FUNDS", "retryClass": "NEVER", "retryable": true, "networkResponseCode": "51", "customerMessage": "Your card was declined. Please try another card.", "merchantMessage": "Insufficient funds; ask the customer for another payment method." }, "cardPresent": { "terminalId": "TID-00012345", "entryMode": "CONTACTLESS", "acceptanceMode": "KEPA_L2", "applicationLabel": "Visa Credit", "aid": "A0000000031010", "cryptogramType": "TC", "tvr": "0000000000", "cvmResult": "PIN" }, "cardNotPresent": { "paymentIntentId": "pi_123", "paymentMethodId": "pm_123", "threeDsStatus": "AUTHENTICATED", "liabilityShift": true, "eci": "05", "setupFutureUsage": "OFF_SESSION" }, "settlementId": "stl_01JQDAY00042", "metadata": {}, "createdAt": "2026-04-09T09:14:22Z", "updatedAt": "2026-04-09T09:14:22Z" }, "emv": { "arc": "00", "issuerAuthData": "3030", "issuerScript71": "string", "issuerScript72": "string" }, "transactionId": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8", "approved": true, "responseCode": "00", "authorizationCode": "A12345", "rrn": "612345678901", "issuerAuthData": "3030", "issuerScript71": "string", "issuerScript72": "string", "message": "Approved" }