REST API

Authentication

In order to use the REST API you must be in possession of an API key that will be provided by Stitch.

Initiate Transaction Request

POST /v/1/transactions/initiate-terminal
Content-Type: application/json
x-api-key: <your API key>
x-exi-auth-ver: V1
x-tenant-id: <your tenant ID>

{
  "paymentMethod": "card",
  "type": "sale",
  "referenceId": "74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d",
  "merchantId": "763e9948-09ba-455e-a8b2-4271ec597ea3",
  "serialNumber": "E00000000001",
  "payerInformation": {
    "payerId": "546789",
    "fullName": "Test Payer",
    "accountCreatedDate": "2019-12-01",
    "email": "test@example.com",
    "mobileNumber": "0723145675",
    "identifyingDocument": {
      "identityDocument": {
        "country": "ZA",
        "number": "5306075800082"
      }
    }
  },
  "amount": {
    "amount": 5000
  },
  "posData": {
    "posReference": "ABC123"
  }
}

Base information

Field Path	Type	Description	Notes / Example
paymentMethod	string	Only `card` is currently supported.	`"card"`
type	string	Can be `sale`, `sale_with_cashback`, `pre_auth` or `refund`.	`"pre_auth"`
referenceId	string	Unique identifier for the transaction request.	`"74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d"`
serialNumber	string	Terminal serial number initiating the transaction.	`"E00000000001"`
merchantId	string	The unique Stitch merchant identifier.	`"763e9948-09ba-455e-a8b2-4271ec597ea3"`

Payer information

Field Path	Type	Description	Notes / Example
payerId	string	Internal ID of the payer at the tenant.	`"546789"`
fullName	string	Full name of the payer.	`"Test Payer"`
accountCreatedDate	date	Date when the payer’s account was originally created (YYYY-MM-DD).	`"2019-12-01"`
email	string	Payer’s email address.	`"test@example.com"`
mobileNumber	string	Payer’s phone number in international or local format.	`"0723145675"`
identifyingDocument.identityDocument.country	string	Country code (ISO 3166-1 alpha-2) of the identity document.	`"ZA"` (South Africa)
identifyingDocument.identityDocument.number	string	ID number from the payer’s identity document.	`"5306075800082"`

Amount information

Field Path	Type	Description	Notes / Example
amount	integer	Numeric amount to charge, in minor units (e.g. cents in ZAR).	`5000`
cashbackAmount	integer	Numeric amount for the cashback, in minor units (e.g. cents in ZAR).	`500`

Initiate Transaction Response

{
  "result": "success"
}

Field Path	Type	Description	Notes / Example
result	string	Indicates the result of the OTA initiation request. Possible values are `success` or `failure`.	`"success"`
error	string	If the result was a `failure` then the error field will provide more details about the failure.	`"No reply, device may be offline"`

Capture Request

POST /v/1/transactions/{transactionId}/capture
Content-Type: application/json
x-api-key: <your API key>
x-exi-auth-ver: V1
x-tenant-id: <your tenant ID>

{
  "referenceId": "74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d",
  "captureData": {
    "amount": 5000
  },
  "payerInformation": {
    "payerId": "546789",
    "fullName": "Test Payer",
    "accountCreatedDate": "2019-12-01",
    "email": "test@example.com",
    "mobileNumber": "0723145675",
    "identifyingDocument": {
      "identityDocument": {
        "country": "ZA",
        "number": "0000000000000"
      }
    }
  }  
}

Base information

Field Path	Type	Description	Notes / Example
referenceId	string	Unique identifier for the capture request.	`"74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d"`

Capture information

Field Path	Type	Description	Notes / Example
amount	integer	Numeric amount to capture, in minor units (e.g. cents). Must be ≤ original Pre-Auth amount.	`5000`

Capture Response

{
"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",
        "cardFingerprint": "C14CD4BD3C208D5312A2E16F518EF599F8089006DB9E6DC1EC1377D66BC2500B"
      },
      "mid": "000000001328",
      "tid": "00001471",
      "approvalCode": "421861"
    },
    "transactionTime": "2025-07-23T07:06:09.623172",
    "voidableUntilTime": "2025-07-23T22:00:00Z",
    "cardNotPresentRefundableStatus": "refundable",
    "paymentMethod": "card"
    }

Base information

Field	Type	Description	Example / Notes
transactionId	string	Unique transaction identifier assigned by Stitch for the transaction request.	`"d5aa4c31-4cd9..."`
referenceId	string	Reference ID from request	`"74026ed3-f7f4..."`
transactionResult	string	Transaction result	`"approved_confirmed"`
transactionType.value	number	Transaction type code	`9`
transactionType.description	string	Human-readable type	`"Goods and Services with Cashback"`
responseCode.*	mixed	Response code metadata (value, description, etc.)	`"00"`, `"Approved"`
paymentMethod	string	Payment method used	`"card"`
voidableUntilTime	date-time	The time that the transaction will be allowed to be voided in ISO 8601 format.	`"2025-07-23T22:00:00Z"`
cardNotPresentRefundableStatus	string	Indicates whether or not a card not present refund is possible for this transaction. Options are `refundable`, `not_refundable` and `unknown`	`"2025-07-23T22:00:00Z"`

Card Transaction Information

Field	Type	Description	Example / Notes
rrn	string	Retrieval reference number	`"350069576949"`
stan	string	System trace audit number	`"777142"`
settlementDate	date	Settlement date	`"2025-07-23"`
merchant.name	string	Merchant name	`"CI Merchant"`
merchant.city	string	Merchant city	`"Cape Town"`
merchant.countryCode	string	Country code	`"ZA"`
amount.amount	number	Transaction amount in minor units	`1600`
amount.currencyCode	string	Currency code	`"ZAR"`
amount.displayValue	string	Display amount	`"R16.00"`
card.maskedPan	string	Masked PAN	`"541333******0036"`
card.binNumber	string	Bank ID Number	`"541333"`
card.scheme	string	Card scheme	`"Mastercard"`
card.cardholderName	string	Cardholder name	`""`
card.expiryYear	string	Expiry year	`"25"`
card.expiryMonth	string	Expiry month	`"12"`
card.countryCode	string	Issuer country code	`"ZA"`
card.cardFingerprint	string	The unique fingerprint for the card used for this transaction	`"C14CD4BD3C208D5312A2E16F518EF599F8089006DB9E6DC1EC1377D66BC2500B"`
mid	string	Merchant ID	`"000000001328"`
tid	string	Terminal ID	`"00001471"`
approvalCode	string	Authorization code	`"421861"`

Void Transaction Request

POST /v/1/transactions/{transactionId}/void
Content-Type: application/json
x-api-key: <your API key>
x-exi-auth-ver: V1
x-tenant-id: <your tenant ID>

{
  "terminal": {
    "serialNumber": "E00000000001"
  }
}

Field Path	Type	Description	Notes / Example
terminal.serialNumber	string	Terminal serial number initiating the transaction.	`"E00000000001"`

Void Transaction Response

{
  "transactionId": "d5aa4c31-4cd9-410b-b20e-bff5a735e4b0",
  "transactionResult": "voided",
  "responseCode": "00"
}

Field	Type	Description	Example / Notes
transactionId	string	Unique transaction identifier assigned by Stitch for the transaction request.	`"d5aa4c31-4cd9..."`
transactionResult	string	Transaction result	`"voided"`
responseCode	mixed	The acquirer response code.	`"00"`

Refund Transaction Request

POST /v/1/transactions/{transactionId}/cnp-refund
Content-Type: application/json
x-api-key: <your API key>
x-exi-auth-ver: V1
x-tenant-id: <your tenant ID>

{
  "referenceId": "74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d",
  "amount": 5000
}

Base information

Field Path	Type	Description	Notes / Example
referenceId	string	Unique identifier for the refund request.	`"74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d"`
amount	integer	Numeric amount to refund, in minor units (e.g. cents or cents in ZAR). This must be less than or equal to the original transaction amount.	`5000`

Refund Transaction Response

{
    "transactionId": "d5aa4c31-4cd9-410b-b20e-bff5a735e4b0",
    "originalTransactionId": "f88ae864-2cbe-4254-a616-b869edd0cf2b",
    "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",
            "cardFingerprint": "C14CD4BD3C208D5312A2E16F518EF599F8089006DB9E6DC1EC1377D66BC2500B"
        },
        "mid": "000000001328",
        "tid": "00001471",
        "approvalCode": "421861"
    },
    "transactionTime": "2025-07-23T07:06:09.623172",
    "voidableUntilTime": "2025-07-23T22:00:00Z",
    "cardNotPresentRefundableStatus": "refundable",
    "paymentMethod": "card",
    "refundBalanceData": {
        "amount": {
            "amount": 10000,
            "currencyCode": "ZAR",
            "displayValue": "R100.00"
        },
        "balance": {
            "amount": 0,
            "currencyCode": "ZAR",
            "displayValue": "R0.00"
        },
        "refundHistory": [
            {
                "transactionId": "f88ae864-2cbe-4254-a616-b869edd0cf2b",
                "referenceId": "ref123",
                "amount": {
                    "amount": 10000,
                    "currencyCode": "ZAR",
                    "displayValue": "R100.00"
                },
                "transactionTime": "2025-07-20T15:17:55.782546203Z"
            }
        ]
    }
}

See Capture Response for the definition of the above fields.

Additional Refund Response Fields

Refunds have mostly similar structure to the Capture Response fields defined above, however it has these in addition:

originalTransactionId refers to the transactionId of the transaction that was refunded. The refund will get a new transactionId as it is considered to be a new transaction.
refundBalanceData contains the current refundable balance of the original transaction as well as a history of all approved refunds that have been submitted against that transaction.

Initiate Transaction Request​

Base information​

Payer information​

Amount information​

Initiate Transaction Response​

Capture Request​

Base information​

Capture information​

Capture Response​

Base information​

Card Transaction Information​

Void Transaction Request​

Void Transaction Response​

Refund Transaction Request​

Base information​

Refund Transaction Response​

Initiate Transaction Request

Base information

Payer information

Amount information

Initiate Transaction Response

Capture Request

Base information

Capture information

Capture Response

Base information

Card Transaction Information

Void Transaction Request

Void Transaction Response

Refund Transaction Request

Base information

Refund Transaction Response