Omni-channel

info

Omni-channel processing is available to merchants who use both Stitch Card and Stitch In-Person.

Omni-channel Tokens

Stitch lets you securely tokenize cards during in-person transactions. These tokens can then be stored and later used to initiate card-not-present (CNP) payments via the Stitch Card API.

• Tokens are returned in the payload of in-person transaction webhooks.
• Tokens are opaque, Base64-encoded strings — treat them as sensitive credentials.
• Tokens are only included for successfully processed in-person card transactions.

Also included in the webhook is an agreementReference which serves as a reference to the in-person transaction during which the cardholder's card was tokenised. This reference must be provided, in conjunction with the token, when initiating successive CNP transactions via Stitch API.

A typical webhook response, containing the token, can be seen below:

{
  "webhookId": "d20826ae-928c-4e4e-8445-9a219124c4ff",
  "webhookType": "transaction",
  "webhookTime": "2025-07-23T07:06:14.255473514Z",
  "terminal": {
    "id": "42004b91-d54b-4b43-8574-43dd119522af",
    "manufacturerSerialNumber": "terminal-reports-serial",
    "manufacturer": "Sunmi",
    "model": "P2 Mini"
  },
  "transaction": {
    "transactionId": "d5aa4c31-4cd9-410b-b20e-bff5a735e4b0",
    "referenceId": "74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d",
    "transactionResult": "approved_confirmed",
    "transactionType": {
      "value": 9,
      "description": "Goods and Services with Cashback"
    },
    "responseCode": {
      "value": "00",
      "description": "Approved or completed successfully",
      "isoCodeDescription": "Approved or completed successfully",
      "terminalOutcomeString": "Approved",
      "receiptString": "Approved",
      "explanation": "The acquirer has approved the transaction. Other factors may impact the final outcome of the transaction."
    },
    "cardTransactionData": {
      "rrn": "350069576949",
      "stan": "777142",
      "settlementDate": "2025-07-23",
      "merchant": {
        "name": "CI Merchant",
        "city": "Cape Town",
        "countryCode": "ZA"
      },
      "amount": {
        "amount": 1600,
        "currencyCode": "ZAR",
        "displayValue": "R16.00"
      },
      "card": {
        "maskedPan": "541333******0036",
        "binNumber": "541333",
        "scheme": "Mastercard",
        "cardholderName": "",
        "expiryYear": "25",
        "expiryMonth": "12",
        "applicationId": "A0000000041010",
        "applicationName": "MASTERCARD",
        "terminalVerificationResult": "0000008001",
        "accountType": {
          "value": 0,
          "description": "Default"
        },
        "productType": "CREDIT",
        "countryCode": "ZA",
        "token": "Y2FyZC81MmQ3ODBmYS0yNzNiLTRmODMtYTc2Ni1mNWUxYjE4NmM1N2Y="
      },
      "mid": "000000001328",
      "tid": "00001471",
      "approvalCode": "421861"
    },
    "transactionTime": "2025-07-23T07:06:09.623172",
    "voidableUntilTime": "2025-07-23T22:00:00Z",
    "cardNotPresentRefundableStatus": "refundable",
    "paymentMethod": "card",
    "agreementReference": "SI9293939"
  }
}

Testing

Specific amounts can be used to generate test omni-channel tokens that can be used to initiate card-not-present (CNP) charges and simulate different failure scenarios.

The table below shows the mapping between amounts and the CNP transaction status reason to replicate real-world failures.

Amount	Status	Reason
101.00	FAILURE	insufficientFunds
303.00	FAILURE	downstreamProviderError
404.00	FAILURE	authorizationFailed
Other	SUCCESS	-

Next Steps

Learn how to initiate card-not-present charges using omni-channel tokens in Omni-channel Tokens.