kepa
Transactions/createTerminalPaymentSession

Start a payment on an assigned terminal

Light up an assigned reader and start one card-present payment.

POST/v1/terminal/payment-sessions
Create this from your POS or server when the customer is ready to pay. kepa sends the amount and currency to the assigned Android terminal, which owns card capture, EMV, PIN, host authorization, and reader completion. Reuse the same Idempotency-Key if this request times out; never create a second session for the same checkout attempt.

Request body

application/json

merchantIdstring

Optional with a merchant API key; the key-bound merchant is authoritative.

terminalIdstringRequired
Example "TID-00012345"
operationenumRequired
PURCHASEREFUND
originalTransactionIdstring

Required for REFUND and forbidden for PURCHASE.

amountMinorintegerRequired
Example 1250
currencyCodestringRequired
Example "USD"
expiresInSecondsinteger

Response

application/json

idstringRequired
merchantIdstringRequired
terminalIdstringRequired
Example "TID-00012345"
deviceIdstringRequired
Example "dev_01JQXYZ123456"
idempotencyKeystringRequired

Stable key the terminal uses for the single host authorization attempt and all safe retries.

Example "sale-01JQXYZ123456"
claimTokenstringRequired

Fencing token issued for this terminal claim. Every device event and authorization must echo it.

operationenumRequired
PURCHASEREFUND
originalTransactionIdstring
amountMinorintegerRequired
Example 1999
currencyCodestringRequired
Example "USD"
statusenumRequired
CREATEDCLAIMEDIN_PROGRESSSUCCEEDEDDECLINEDCANCELEDFAILEDEXPIREDRECOVERY_REQUIRED
paymentIdstring
Example "0195d46e-7088-7cc4-a9b2-5f9273cd63b8"
failureCodestring
finalAmountMinorinteger

Final amount authorized after any terminal tip.

tipAmountMinorinteger
Example 0
lastEventSequenceintegerRequired
expiresAtstring · ISO 8601Required
Example "2026-04-09T09:14:22Z"
processingExpiresAtstring · ISO 8601

Fifteen-minute deadline for a reader operation already in progress. If it passes without a verified final event, status becomes RECOVERY_REQUIRED and the command is never automatically reissued.

Example "2026-04-09T09:14:22Z"
authorizationStartedAtstring · ISO 8601

Time the host serialized this session's single authorization attempt.

Example "2026-04-09T09:14:22Z"
completedAtstring · ISO 8601
Example "2026-04-09T09:14:22Z"
createdAtstring · ISO 8601
Example "2026-04-09T09:14:22Z"
updatedAtstring · ISO 8601
Example "2026-04-09T09:14:22Z"
Good to know
  • The terminal uses the session's exact currency, even when it differs from the device's default currency.
  • expiresAt is the deadline to start reading a card. Once the reader starts, processingExpiresAt becomes the separate deadline for finishing the in-flight transaction.
  • A session that loses contact while processing becomes RECOVERY_REQUIRED. It is never automatically sent to the reader again, because doing so could charge the card twice.

createTerminalPaymentSession

POSTGo API
https://api.kepapay.co/v1/terminal/payment-sessions
Request
curl https://api.kepapay.co/v1/terminal/payment-sessions \
  -H "X-Api-Key: $KEPA_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "string",
  "terminalId": "TID-00012345",
  "operation": "PURCHASE",
  "originalTransactionId": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8",
  "amountMinor": 1250,
  "currencyCode": "USD",
  "expiresInSeconds": 300
}'
Response
{
  "id": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8",
  "merchantId": "string",
  "terminalId": "TID-00012345",
  "deviceId": "dev_01JQXYZ123456",
  "idempotencyKey": "sale-01JQXYZ123456",
  "claimToken": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8",
  "operation": "PURCHASE",
  "originalTransactionId": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8",
  "amountMinor": 1999,
  "currencyCode": "USD",
  "status": "CREATED",
  "paymentId": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8",
  "failureCode": "string",
  "finalAmountMinor": 0,
  "tipAmountMinor": 0,
  "lastEventSequence": 0,
  "expiresAt": "2026-04-09T09:14:22Z",
  "processingExpiresAt": "2026-04-09T09:14:22Z",
  "authorizationStartedAt": "2026-04-09T09:14:22Z",
  "completedAt": "2026-04-09T09:14:22Z",
  "createdAt": "2026-04-09T09:14:22Z",
  "updatedAt": "2026-04-09T09:14:22Z"
}