kepa
Transactions/cancelTerminalPaymentSession

Cancel an unclaimed terminal payment command

Cancel a queued reader command before the terminal claims it.

POST/v1/terminal/payment-sessions/{id}/cancel
Use this only while a session is still waiting for its terminal. Once card processing starts, cancellation moves to the terminal/payment recovery flow so an issuer authorization cannot be hidden behind a canceled command.
Path parameters
idstringRequired

Request body

application/json

merchantIdstring

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
  • A 409 means the terminal has already claimed the command; poll the session instead of creating another one.
  • Cancellation never interrupts an active EMV or PIN exchange.

cancelTerminalPaymentSession

POSTGo API
https://api.kepapay.co/v1/terminal/payment-sessions/{id}/cancel
Request
curl https://api.kepapay.co/v1/terminal/payment-sessions/{id}/cancel \
  -H "X-Api-Key: $KEPA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "string"
}'
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"
}