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 (including value and description, as per Response Codes)	"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>

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 (see Response Codes).	"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.

Response Codes

The Stitch in-person payments platform returns response codes of the following values:

Code	Description	Explanation
00	Approved or completed successfully	The acquirer has approved the transaction. Other factors may impact the final outcome of the transaction.
01	Refer to card issuer	The transaction was rejected with no reason provided. The fix requires contacting the card-issuing bank for an explanation.
02	Refer to card issuer's special conditions	The cardholder's bank rejected the transaction. Contact the bank for the explanation and fix.
03	Invalid merchant	Invalid merchant: the payment information is entered incorrectly or if the merchant account or credit card terminal isn't configured properly. Contact the payment processor.
04	Pick-up	The transaction was rejected, and the merchant has been instructed to hold onto the card until they have a chance to contact the cardholder's bank.
05	Do not honor	The cardholder's bank instructs you not to accept payment until the merchant contacts the bank directly.
06	Error	The card-issuing bank detected an error but can't specify what it is. The merchant can try the card again or call the bank directly for further instructions.
07	Pick-up card, special condition	The card-issuing bank has detected fraud. Both parties should contact the bank before using the card again.
08	Honour with identification	Transaction processed successfully - identification NOT required except in Australia, New Zealand, Hong Kong, Singapore, Macau where identification is required. This code is returned by some banks in place of 00 response.
09	Request in progress	The card issuer has indicated there is a problem with the card number. The customer should contact their bank and/or use an alternate credit card.
10	Approved for partial amount	The card-issuing bank only accepted a portion of the payment - normally due to insufficient funds or credit limits.
11	Approved (vip)	Rapid Response Code. This means the payment has been approved. This is sometimes returned in place of the 00 response. Applies to Australia, New Zealand, Hong Kong, Singapore, Macau.
12	Invalid transaction	The sale was rejected due to any number of issues (like when trying to reverse a charge). You can try the transaction again or call the card-issuing bank directly.
13	Invalid amount	The transaction was declined - often because of invalid characters or symbols (e.g., # or &). Try inputting the amount again and see if the sale goes through.
14	Invalid card number (no such number)	The transaction was declined - often because of invalid characters or symbols or the card account number is incorrect. Try initiating the sale again. If that fails, contact the bank directly.
15	No such issuer (invalid IIN)	No issuer for the card could be found to which to route this request.
16	Approved, update track 3	The payment has been approved by the card issuer. This is sometimes returned instead of the 00 response.
17	Customer cancellation	The customer has voided or reversed the transaction. The sale will not go through unless you use a different payment method.
18	Customer dispute
19	Re-enter transaction	The sale was declined due to an unknown error. Try running the sale again by re-entering all the information more carefully a second time.
1A	Additional consumer authentication required
1B	Cashback not allowed
1C	Cashback amount exceeded
1D	Surcharge amount not permitted for card product
1E	Surcharge not permitted by selected network
1F	Exceeds pre-authorized amount
1G	Currency unacceptable to card issuer
1H	Authorization lifecycle unacceptable
1I	Authorization lifecycle has expired
1J	Message sequence number error
1K	Payment date invalid
20	Invalid response
21	No action taken
22	Suspected malfunction
23	Unacceptable transaction fee
24	File update not supported by receiver	Transaction was declined due to an acquirer configuration issue. Contact the acquirer.
25	Unable to locate record on file	Generated if a reversal request (0400) or reversal advice (0420) message is received which contains field 127.11 (Original key) but for which Transaction Manager could not locate the original transaction record.
26	Duplicate file update record, old record replaced
27	File update field edit error	Transaction was declined due to an acquirer configuration issue. Contact the acquirer.
28	File update file locked out	The transaction was declined for an unspecified reason. Try running the sale again. If that doesn't work, contact the card-issuing bank directly.
29	File update not successful	The transaction was declined for an unspecified reason. Try running the sale again. If that doesn't work, contact the acquirer.
30	Format error	Returned from the acquirer if field(s) are either missing or incorrectly packed in the ISO message.
31	Acquirer bank not supported by switch
32	Completed partially	Generated if a transaction completion (0202) message was approved for a different final amount to the amount requested in the original transaction request (0200) message.
33	Expired card, pick up new card
34	Suspected fraud
35	Card acceptor contact acquirer
36	Restricted card
37	Card acceptor call acquirer security
38	Allowable PIN tries exceeded	This code is also flagged as code 75 on some systems. The sale is rejected because the customer's PIN has been entered incorrectly too many times. Ask for an alternate payment method.
39	No credit account
40	Requested function not supported	Transaction was declined due to an acquirer configuration issue. Contact the acquirer.
41	Lost card	The card has been reported stolen or lost and cannot be used to complete the sale. Try the transaction again with a different payment method.
42	No universal account	Generated if a transaction is received with the account type sub field of the processing code (field 3) set to '00' (default account) and either there is no default account attached to the card product or card, or there is more than one account attached to the card product or the card without an indication of which is the default account.
43	Stolen card, pick-up	The card has been reported stolen or lost and cannot be used for this transaction. Try running the sale again with an alternate payment method.
44	No investment account	Generated if a transaction is received with the account type sub field of the processing code (field 3) set to '50' (investment account) and there is no investment account attached to the card product or card.
51	Not sufficient funds	The customer's account doesn't have enough funds to cover the sale. Ask for an alternate payment method or contact the user's bank directly.
52	No checking account	Generated if a transaction is received with the account type sub field of the processing code (field 3) set to '20' (check/cheque) and there is no check account attached to the card product or card.
53	No savings account	Generated if a transaction is received with the account type sub field of the processing code (field 3) set to '10' (savings account) and there is no savings account attached to the card product or card.
54	Expired card	The customer's card has expired and is no longer valid. Ask for an alternate payment method.
55	Incorrect personal identification number	Generated if the maximum number of PIN retries has not yet been exceeded and the PIN was found to be incorrect during PIN verification. Terminal should restart the transaction with the same parameters and all interfaces.
56	No card record	Transaction was received containing a PAN that matches no configured BIN and therefore no card product. Contact acquirer and/or issuer.
57	transaction not permitted to cardholder	The card is valid - but not for that particular sale or transaction. Ask for an alternate payment method.
58	transaction not permitted to terminal	Merchant account or credit card terminal isn't configured properly. You may need to switch to cash or check to complete the sale. You should also follow up with your payment processor to fix your merchant account setup.
59	Suspected fraud	The card-issuing bank has detected fraud. Ask for an alternate payment method (and contact the bank directly).
60	Card acceptor contact acquirer
61	Exceeds withdrawal amount limit	Card velocity limits breached.
62	Restricted card	This code happens in cases where your merchant account doesn't support the customer's card network (e.g., Discover or American Express).
63	Security violation	The CVV, CVC or CID security code on the back of the card wasn't entered correctly. Try running the entire transaction again with the proper security code, expiration date and account number.
64	original amount incorrect
65	Exceeds withdrawal limit / request PIN	Activity limit exceeded or the sale would push the customer over their credit limit. Terminal should restart the transaction with the same parameters and fall-forward interfaces or if Single Tap and PIN supported prompt for the PIN.
66	Card acceptor call acquirer's security department
67	Hard capture (requires that card be picked up at atm)
68	Response received too late	The card issuer's bank did not respond in time.
75	Allowable number of PIN tries exceeded	Number of times a cardholder has entered an incorrect PIN exceeds the configured maximum number of failed PIN entry attempts permitted to a cardholder.
76	Invalid/non-existent to account specified
77	Invalid/non-existent from account specified
78	Invalid/non-existent account specified (general)
79	Reserved for private use
80	Reserved for private use
81	Domestic debit transaction not allowed (regional use only)
82	Reserved for private use
83	Reserved for private use
84	Invalid authorization life-cycle
85	Not declined Valid for all zero amount transactions	Error code 85 may also mean that there is no particular reason to decline. If there's no reason to decline, then why didn't the payment go through? Well, there was still a problem securing payment. While this may sound confusing, this error code works as a sort of catch-all for unexplained errors. There is no particular problem to address, but an error has still occurred.
86	PIN validation not possible decline
87	Purchase amount only, no cash back allowed
88	Cryptographic failure decline
89	Unacceptable PIN transaction
90	Cutoff is in process(switch ending a day's business and starting the next. Transaction can be sent again in a few minutes)
91	Issuer is unavailable.	Either the payment processor or terminal was unable to complete the transaction. Try running the sale again. If that fails, contact the bank and payment processor directly.
92	Financial institution or intermediate network facility cannot be found for routing
93	transaction cannot be completed. violation of law	The card-issuing bank has frozen the customer's account (for any number of reasons). Call the bank directly for next steps.
94	Duplicate transmission	Acquirer declined based on acquirer criteria to match transaction requests.
95	Reconcile error
96	System malfunction	The payment processor has experienced an error. Try running the sale again - or contact the payment processor directly.
R9	Reserved for private use R9
S0	Reserved for private use S0
U0	ARQC failure decline
U1	Security module parameter error
U2	Security module failure
U3	Key1 record not found
U4	ATC check failure
U5	CVR decline
U6	TVR decline
O5	Single Tap and PIN SCA required	Reply from Base24 to request for single-tap + PIN, converted to '65'.
N0	Acquirer transaction timed out	Stitch sent the transaction but didn't get a response within a reasonable amount of time.
N1	Acquirer rejected message	Stitch sent the message but the acquirer refused to accept the message, possibly because it is malformed.
N2	Acquirer original transaction not found	Stitch tried to reverse or complete a transaction but the acquirer can't find the transaction we're referring to.
N3	Acquirer response could not be authenticated	Stitch sent a request and got a response, but we couldn't verify the signature on the response so we can't accept it.
N4	Error while sending request to acquirer	Something went wrong while trying to send the request to the acquirer. It remains possible that they received it.
N5	Terminal not configured to transact	No payment routes have been configured for the terminal against the merchant it is assigned to.
ZA	Contactless not available. Please insert card.	Stitch response code is equivalent to 65, but Stitch uses it to tell the terminal to silently fall forward to chip and PIN.
Z5	Valid account but amount not supported.	Account valid, but the transaction amount is not supported.
N99	Error translating	ISO adaptor has not completed translating the input when an error occurs so we then don't attempt to reverse it as we've not sent it upstream.
P9	Enter lesser amount.	The amount is too large, the transaction amount should be less.
X93	Payment failed	This response code indicates that the merchant should refer to the error message for this alternative payment method failure.
X94	Payment failed	This response code indicates that the merchant should refer to the error message for this alternative payment method failure.
X95	Currency unacceptable for merchant	The merchant is not allowed to accept the currency sent
X96	Acquirer private use	This response code carries an acquirer private use response code and description
X97	Refund amount is not valid	Stitch failed this transaction as the refund amount requested is invalid for this transaction.
X98	Error storing transaction for clearing	Stitch could process the transaction but not complete it for clearing and settlement instructions. Transaction will be reversed.
X99	No or unknown response code	Fallback response code if a ISO response code cannot be mapped or are unrecognized.