v2

latestOpenAPI 3.1.0Proprietary2026-07-261022123.6 KB

Create a terminal session

Creates a new terminal session to initiate a payment on a specified terminal device.

post/terminal-sessions

Request body

terminalstring required

The unique identifier of the terminal device where the payment should be processed

noncestring required

A unique identifier for this specific resource. Use the nonce to ensure idempotency. If you attempt to create a resource with a nonce that has already been used, an error will be returned.

externalReferencestring

A custom identifier that you can use to reference this resource in your own system. Multiple resources can share the same external reference, so this is not enforced as unique.

metadataobject

Additional metadata to be associated with the terminal session.

Response

Returns a new terminal session object

idstring required

The unique identifier for this terminal session.

terminalstring required

The terminal unique identifier.

source'api' | 'standalone_app' | 'sdk' required

The channel that created the terminal session. api indicates the REST API, standalone_app indicates the standalone terminal app, and sdk indicates the Terminal SDK.

status'pending' | 'success' | 'failure' required

The current status of the terminal session. pending indicates the session is awaiting completion on the terminal, success indicates the payment was processed successfully, and failure indicates the session did not complete successfully.

The reason the terminal session failed. Only present when the status is failure. Possible values are expired (session timed out), cancelled_by_terminal (operator cancelled on the device), cancelled_by_api (cancelled via API request), offline_terminal (terminal was not connected), busy_terminal (terminal was processing another session), or attempt_limit_exceeded (maximum number of failed attempts for this terminal session reached).

noncestring required

A unique identifier for this specific resource. Use the nonce to ensure idempotency. If you attempt to create a resource with a nonce that has already been used, an error will be returned.

externalReferencestring

A custom identifier that you can use to reference this resource in your own system. Multiple resources can share the same external reference, so this is not enforced as unique.

metadataMetadata required

A set of key-value pairs that you can attach to the resource. Use metadata to store additional, structured information relevant to your integration.

createdAtstring date-time required

The UTC timestamp indicating when the terminal session was created. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:30:00Z).

updatedAtstring date-time required

The UTC timestamp indicating when the terminal session was last modified, such as when the status changes. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:35:00Z).

Example response

{
  "outcome": {
    "charge": {
      "card": {
        "id": "card_1234567890",
        "bin": "42424242",
        "last4": "4242",
        "expiry": {
          "month": "12",
          "year": "29"
        },
        "network": "visa",
        "fundingType": "debit",
        "issuer": {
          "name": "standard bank",
          "country": "ZA"
        }
      },
      "failure": {
        "resultCode": {
          "value": "05",
          "descriptor": "do_not_honour",
          "detail": "Do Not Honour indicates that the card issuer declined the transaction without providing a specific reason. The cardholder should contact their bank for more information."
        }
      }
    }
  }
}