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>
{
"referenceId": "74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d",
"serialNumber": "E00000000001",
"merchantId": "763e9948-09ba-455e-a8b2-4271ec597ea3",
"payerInformation": {
"payerId": "546789",
"fullName": "Test Payer",
"accountCreatedDate": "2019-12-01",
"email": "test@example.com",
"mobileNumber": "0723145675",
"identifyingDocument": {
"identityDocument": {
"country": "ZA",
"number": "0000000000000"
}
}
},
"amount": {
"amount": 5000,
"currencyCode": "ZAR"
},
"extendedTransactionType": "none",
"posData": {
"tipAmount": "500"
}
}
Base information
Field Path | Type | Description | Notes / Example |
---|---|---|---|
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" |
extendedTransactionType | string | Can be none or pre_authorization . | "pre_authorization" |
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" |
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 or cents in ZAR). | 5000 |
currencyCode | string | ISO 4217 currency code. | ZAR |
Initiate Transaction Response
{
"transactionId": "1e40c500-20a7-442b-b35e-35d5c3fac0d4"
}
Field Path | Type | Description | Notes / Example |
---|---|---|---|
transactionId | string | Unique transaction identifier assigned by Stitch for the transaction request. | "1e40c500-20a7-442b-b35e-35d5c3fac0d4" |
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.