kepa
Transactions/getTerminalPaymentSession

Retrieve terminal payment progress

Poll the reader payment until it reaches a final, decline, or recovery state.

GET/v1/terminal/payment-sessions/{id}
Returns the current payment session and its ordered device events. Treat the linked paymentId as the financial record: SUCCEEDED and DECLINED are only accepted after kepa verifies that payment belongs to the same merchant and terminal and has the exact session amount, currency, operation, and outcome.
Path parameters
idstringRequired

Response

application/json

sessionobjectRequired
eventsarray of objectsRequired
Good to know
  • Stop polling on SUCCEEDED, DECLINED, CANCELED, FAILED, EXPIRED, or RECOVERY_REQUIRED.
  • RECOVERY_REQUIRED means the result cannot safely be inferred from connectivity alone. Query the linked payment when present and follow your reconciliation workflow; do not start a replacement payment automatically.
  • Events are contiguous and replay-safe. A device may retry the same sequence with identical content, but cannot change an event after the host accepts it.

getTerminalPaymentSession

GETGo API
https://api.kepapay.co/v1/terminal/payment-sessions/{id}
Request
curl https://api.kepapay.co/v1/terminal/payment-sessions/{id} \
  -H "X-Api-Key: $KEPA_SECRET_KEY"
Response
{
  "session": {
    "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"
  },
  "events": [
    {
      "sequence": 0,
      "eventType": "string",
      "status": "string",
      "paymentId": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8",
      "failureCode": "string",
      "claimToken": "0195d46e-7088-7cc4-a9b2-5f9273cd63b8"
    }
  ]
}