--- title: "Get a terminal session" method: GET path: "/terminal-sessions/{id}" --- # Get a terminal session `GET /terminal-sessions/{id}` Retrieves a terminal session by its unique identifier. ## Path parameters - `id` string, required ## Response `200` Returns a terminal session object - TerminalSession - `id` string, required — The unique identifier for this terminal session. - `terminal` string, 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. - `intent` union, required — Defines the purpose of the terminal session, such as processing a charge, disbursement, or refund. Exactly one of `charge`, `disbursement`, or `refund` will be present. - object — A terminal session that processes a charge. - `charge` object, required — The charge to be processed during this terminal session. - `amount` number, required — The charge amount in the currency's major unit (e.g., 350.5 for R350.50). - `currency` string, required — The charge currency in ISO 4217 format. Only "ZAR" is currently supported. - `cashback` object — Optional cashback to be dispensed to the customer in addition to the charge amount. - `amount` number — The cashback amount in the currency's major unit (e.g., 50.0 for R50.00). - `currency` string — The cashback currency in ISO 4217 format. Only "ZAR" is currently supported. - object — A terminal session that processes a disbursement. - `disbursement` object, required — The disbursement to be processed during this terminal session. - `amount` number, required — The disbursement amount in the currency's major unit (e.g., 150.0 for R150.00). - `currency` string, required — The disbursement currency in ISO 4217 format. Only "ZAR" is currently supported. - object — A terminal session that processes a refund. - `refund` object, required — The refund to be processed during this terminal session. - `terminalSession` string, required — The original terminal session unique identifier. - `amount` number, required — The refund amount in the currency's major unit (e.g., 45.0 for R45.00). - `currency` string, required — The refund currency in ISO 4217 format. Only "ZAR" is currently supported. - `reason` 'fraud' | 'requested_by_customer' | 'duplicate_charge', required — The reason for the refund. - `customer` Customer - `name` string — The name of the customer. - `email` string — The email of the customer. - `phone` string — The phone number of the customer, including country code (e.g., +27612345678). - `identifyingDocument` IdentifyingDocument - `type` 'identity_document' | 'passport' | 'temporary_residence' — Type of identifying document. - `country` string — Country code of the document, in ISO 3166-1 alpha-2 format (e.g., ZA). - `number` string — The document number. - `externalReference` string — A custom identifier that you use to reference this customer in your own system. - `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. - `failureReason` 'expired' | 'cancelled_by_terminal' | 'cancelled_by_api' | 'offline_terminal' | 'busy_terminal' | 'attempt_limit_exceeded' — 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). - `outcome` union — The outcome of the terminal session. This is only present when the status is `success`. Contains either a `charge`, `disbursement`, or `refund` matching the session intent. Exactly one of `charge`, `disbursement`, or `refund` will be present. - object — The outcome of a terminal session that processed a charge. - `charge` InPersonCardCharge, required - `id` string, required — The unique identifier for this charge. - `amount` number, required — The amount to be charged in the currency's major unit (e.g., 350.5 for R350.50). - `currency` string, required — The charge currency in ISO 4217 format. Only "ZAR" is currently supported. - `status` 'processing' | 'requires_capture' | 'requires_interaction' | 'success' | 'failure' | 'cancelled', required — The current status of the charge. `processing` indicates the charge is being processed, `requires_capture` indicates the charge requires a capture request to settle the funds, `requires_interaction` indicates the charge requires a manual interaction from the customer, `success` indicates the charge was processed successfully, `failure` indicates the charge did not complete successfully, and `cancelled` indicates the charge was cancelled. - `nonce` string — 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. - `externalReference` string — 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. - `metadata` Metadata, 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. - `createdAt` string, date-time, required — The UTC timestamp indicating when the charge was created. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:30:00Z). - `updatedAt` string, date-time, required — The UTC timestamp indicating when the charge was last modified, such as when the status changes. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:35:00Z). - `type` 'in_person_card', required — The type of charge. For in-person card charges, this is always `in_person_card`. - `card` CardMetadata, required - `bin` string, required — The first 8 digits of the card number. - `last4` string, required — The last 4 digits of the card number. - `expiry` object, required - `month` string, required — The expiry month of the card in MM format (01-12). - `year` string, required — The expiry year of the card in YY format (e.g., 25 for 2025). - `network` 'visa' | 'mastercard' | 'amex' | 'diners' — The network of the card. - `fundingType` 'credit' | 'debit' | 'prepaid' — The funding type of the card. - `issuer` object - `name` string — The name of the financial institution that issued the card. - `country` string — The country code (ISO 3166-1 alpha-2) of the card issuer (e.g., "ZA" for South Africa). - `cashback` object — Cashback dispensed to the customer in addition to the charge amount. - `amount` object, required - `quantity` number, required — The cashback amount in the currency's major unit. - `currency` 'ZAR', required — The currency in ISO 4217 format. - `retrievalReferenceNumber` string, required — The retrieval reference number (RRN) assigned by the card network for this transaction. - `networkTransactionIdentifier` string — The network transaction identifier assigned by the card network. - `failure` object — Details about the failure. Only present when the charge status is `failure`. - `reason` 'authorization_failed', required — The reason for the failure. - `resultCode` object — The result code from the card network. This is only present when the failure reason is `authorization_failed`. - `value` string, required — The numeric result code value. - `descriptor` string, required — A machine-readable descriptor for the result code. - `detail` string, required — A human-readable explanation of the result code. - object — The outcome of a terminal session that processed a disbursement. - `disbursement` InPersonCardDisbursement, required - `id` string, required — The unique identifier for this charge. - `amount` number, required — The amount to be charged in the currency's major unit (e.g., 350.5 for R350.50). - `currency` string, required — The charge currency in ISO 4217 format. Only "ZAR" is currently supported. - `status` 'processing' | 'requires_capture' | 'requires_interaction' | 'success' | 'failure' | 'cancelled', required — The current status of the charge. `processing` indicates the charge is being processed, `requires_capture` indicates the charge requires a capture request to settle the funds, `requires_interaction` indicates the charge requires a manual interaction from the customer, `success` indicates the charge was processed successfully, `failure` indicates the charge did not complete successfully, and `cancelled` indicates the charge was cancelled. - `nonce` string — 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. - `externalReference` string — 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. - `metadata` Metadata, 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. - `createdAt` string, date-time, required — The UTC timestamp indicating when the charge was created. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:30:00Z). - `updatedAt` string, date-time, required — The UTC timestamp indicating when the charge was last modified, such as when the status changes. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:35:00Z). - `type` 'in_person_card', required — The type of disbursement. For in-person card disbursements, this is always `in_person_card`. - `card` CardMetadata, required - `bin` string, required — The first 8 digits of the card number. - `last4` string, required — The last 4 digits of the card number. - `expiry` object, required - `month` string, required — The expiry month of the card in MM format (01-12). - `year` string, required — The expiry year of the card in YY format (e.g., 25 for 2025). - `network` 'visa' | 'mastercard' | 'amex' | 'diners' — The network of the card. - `fundingType` 'credit' | 'debit' | 'prepaid' — The funding type of the card. - `issuer` object - `name` string — The name of the financial institution that issued the card. - `country` string — The country code (ISO 3166-1 alpha-2) of the card issuer (e.g., "ZA" for South Africa). - `retrievalReferenceNumber` string, required — The retrieval reference number (RRN) assigned by the card network for this transaction. - `networkTransactionIdentifier` string — The network transaction identifier assigned by the card network. - object — The outcome of a terminal session that processed a refund. - `refund` Refund, required - `id` string, required — The unique identifier for this refund. - `type` 'card' | 'in_person_card' — The type of refund. - `charge` string, required — The unique identifier of the charge being refunded. - `amount` number, required — The refund amount in the currency's major unit (e.g., 30.0 for R30.00). - `currency` 'ZAR', required — The refund currency in ISO 4217 format. Only "ZAR" is currently supported. - `reason` 'fraud' | 'requested_by_customer' | 'duplicate_charge', required — The reason for the refund. - `status` 'processing' | 'success' | 'paused' | 'failure', required — The current status of the refund. `processing` indicates the refund is being processed, `success` indicates the refund was processed successfully, `paused` indicates the refund is paused pending resolution, and `failure` indicates the refund did not complete successfully. - `nonce` string, 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. - `metadata` Metadata — A set of key-value pairs that you can attach to the resource. Use metadata to store additional, structured information relevant to your integration. - `createdAt` string, date-time, required — The UTC timestamp indicating when the refund was created. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:30:00Z). - `updatedAt` string, date-time, required — The UTC timestamp indicating when the refund was last modified, such as when the status changes. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:35:00Z). - `nonce` string, 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. - `externalReference` string — 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. - `metadata` Metadata, 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. - `createdAt` string, 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). - `updatedAt` string, 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). --- [API](https://skmtc.dev/stitch/apis/stitch-api.md) · [All operations](https://skmtc.dev/stitch/apis/stitch-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stitch/stitch-api/revisions/8c5a258567d0/schema)