Skip to main content

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 PathTypeDescriptionNotes / Example
referenceIdstringUnique identifier for the transaction request."74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d"
serialNumberstringTerminal serial number initiating the transaction."E00000000001"
merchantIdstringThe unique Stitch merchant identifier."763e9948-09ba-455e-a8b2-4271ec597ea3"
extendedTransactionTypestringCan be none or pre_authorization."pre_authorization"

Payer information

Field PathTypeDescriptionNotes / Example
payerIdstringInternal ID of the payer at the tenant."546789"
fullNamestringFull name of the payer."Test Payer"
accountCreatedDatedateDate when the payer’s account was originally created (YYYY-MM-DD)."2019-12-01"
emailstringPayer’s email address."test@example.com"
mobileNumberstringPayer’s phone number in international or local format."0723145675"
identifyingDocument.identityDocument.countrystringCountry code (ISO 3166-1 alpha-2) of the identity document."ZA" (South Africa)
identifyingDocument.identityDocument.numberstringID number from the payer’s identity document."5306075800082"

Amount information

Field PathTypeDescriptionNotes / Example
amountintegerNumeric amount to charge, in minor units (e.g. cents or cents in ZAR).5000
currencyCodestringISO 4217 currency code.ZAR

Initiate Transaction Response

{
"transactionId": "1e40c500-20a7-442b-b35e-35d5c3fac0d4"
}
Field PathTypeDescriptionNotes / Example
transactionIdstringUnique 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 PathTypeDescriptionNotes / Example
referenceIdstringUnique identifier for the capture request."74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d"
Capture information
Field PathTypeDescriptionNotes / Example
amountintegerNumeric 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

FieldTypeDescriptionExample / Notes
transactionIdstringUnique transaction identifier assigned by Stitch for the transaction request."d5aa4c31-4cd9..."
referenceIdstringReference ID from request"74026ed3-f7f4..."
transactionResultstringTransaction result"approved_confirmed"
transactionType.valuenumberTransaction type code9
transactionType.descriptionstringHuman-readable type"Goods and Services with Cashback"
responseCode.*mixedResponse code metadata (value, description, etc.)"00", "Approved"
paymentMethodstringPayment method used"card"
voidableUntilTimedate-timeThe time that the transaction will be allowed to be voided in ISO 8601 format."2025-07-23T22:00:00Z"
cardNotPresentRefundableStatusstringIndicates 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

FieldTypeDescriptionExample / Notes
rrnstringRetrieval reference number"350069576949"
stanstringSystem trace audit number"777142"
settlementDatedateSettlement date"2025-07-23"
merchant.namestringMerchant name"CI Merchant"
merchant.citystringMerchant city"Cape Town"
merchant.countryCodestringCountry code"ZA"
amount.amountnumberTransaction amount in minor units1600
amount.currencyCodestringCurrency code"ZAR"
amount.displayValuestringDisplay amount"R16.00"
card.maskedPanstringMasked PAN"541333******0036"
card.binNumberstringBank ID Number"541333"
card.schemestringCard scheme"Mastercard"
card.cardholderNamestringCardholder name""
card.expiryYearstringExpiry year"25"
card.expiryMonthstringExpiry month"12"
card.countryCodestringIssuer country code"ZA"
card.cardFingerprintstringThe unique fingerprint for the card used for this transaction"C14CD4BD3C208D5312A2E16F518EF599F8089006DB9E6DC1EC1377D66BC2500B"
midstringMerchant ID"000000001328"
tidstringTerminal ID"00001471"
approvalCodestringAuthorization 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 PathTypeDescriptionNotes / Example
terminal.serialNumberstringTerminal serial number initiating the transaction."E00000000001"

Void Transaction Response

{
"transactionId": "d5aa4c31-4cd9-410b-b20e-bff5a735e4b0",
"transactionResult": "voided",
"responseCode": "00"
}
FieldTypeDescriptionExample / Notes
transactionIdstringUnique transaction identifier assigned by Stitch for the transaction request."d5aa4c31-4cd9..."
transactionResultstringTransaction result"voided"
responseCodemixedThe 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 PathTypeDescriptionNotes / Example
referenceIdstringUnique identifier for the refund request."74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d"
amountintegerNumeric 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.