Pre-Authorization

Integration Flow

The transaction pre-authorization integration flow works as follows:

The client’s point-of-sale (POS) system initiates a transaction by calling the Stitch backend API.
The initiation request must include the terminal serial number so Stitch can identify which terminal to use for in-store processing.
The specified terminal then processes the transaction with the acquirer using Stitch’s existing APIs.
Once the transaction is completed, Stitch sends a webhook to the client’s system indicating the result of the pre-authorization.

Payloads

Preauthorization Initiation Request

Endpoint:

POST https://api.exipay.com/v/1/transactions/initiate-terminal

Headers:

Content-Type: application/json
x-api-key: <your API key>
x-exi-auth-ver: V1
x-tenant-id: <your tenant ID>

Request Body:

{
  "referenceId": "74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d",
  "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,
    "currencyCode": "ZAR"
  }
}

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"
payerInformation.payerId	string	Internal ID of the payer at the tenant.	"546789"
payerInformation.fullName	string	Full name of the payer.	"Test Payer"
payerInformation.accountCreatedDate	date	Date when the payer’s account was originally created (YYYY‑MM‑DD).	"2019-12-01"
payerInformation.email	string	Payer’s email address.	"test@example.com"
payerInformation.mobileNumber	string	Payer’s phone number in international or local format.	"0723145675"
payerInformation.identifyingDocument.identityDocument.country	string	Country code (ISO 3166‑1 alpha‑2) of the identity document.	"ZA" (South Africa)
payerInformation.identifyingDocument.identityDocument.number	string	ID number from the payer’s identity document.	"5306075800082"
amount.amount	number	Numeric amount to charge, in minor units (e.g. cents or cents in ZAR).	5000
amount.currencyCode	string	ISO 4217 currency code.	"ZAR"

Response Body:

{
  "transactionId": "1e40c500-20a7-442b-b35e-35d5c3fac0d4"
}

Field	Type	Description	Example
transactionId	string	Unique identifier for the initiated Stitch transaction.	"1e40c500-20a7-442b-b35e-35d5c3fac0d4"

Webhooks

See more information about how webhooks are handled here: https://docs.test.exipay.com/docs/webhook/intro

Webhook Body:

{
  "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",
    "externalSerialNumber": "",
    "manufacturer": "Sunmi",
    "model": "P2 Mini",
    "firmwareVersions": {
      "firmwareVersion": "x.y"
    },
    "batteryPercent": 50
  },
  "transaction": {
    "transactionId": "d5aa4c31-4cd9-410b-b20e-bff5a735e4b0",
    "referenceId": "74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d",
    "transactionResult": "authorized_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"
      },
      "mid": "000000001328",
      "tid": "00001471",
      "approvalCode": "421861"
    },
    "transactionTime": "2025-07-23T07:06:09.623172",
    "paymentMethod": "card"
  }
}

Field	Type	Description	Example / Notes
webhookId	string	Unique ID for the webhook event	"d20826ae-928c-4e4e-8445-9a219124c4ff"
webhookType	string	Type of webhook (e.g. transaction)	"transaction"
webhookTime	ISO 8601 string	Time the webhook was triggered	"2025-07-23T07:06:14.255Z"
terminal.id	string	Terminal ID in Stitch system	"42004b91-d54b..."
terminal.manufacturerSerialNumber	string	Manufacturer-assigned terminal serial number	"terminal-reports-serial"
terminal.manufacturer	string	Name of manufacturer	"Sunmi"
terminal.model	string	Model name	"P2 Mini"
terminal.firmwareVersions.firmwareVersion	string	Terminal firmware version	"x.y"
terminal.batteryPercent	number	Terminal battery percentage	50
transaction.transactionId	string	Internal transaction ID	"d5aa4c31-4cd9..."
transaction.referenceId	string	Reference ID from request	"74026ed3-f7f4..."
transaction.transactionResult	string	Transaction result	"approved_confirmed"
transaction.transactionType.value	number	Transaction type code	9
transaction.transactionType.description	string	Human-readable type	"Goods and Services with Cashback"
transaction.responseCode.*	mixed	Response code metadata	"00", "Approved"
transaction.cardTransactionData.rrn	string	Retrieval reference number	"350069576949"
transaction.cardTransactionData.stan	string	System trace audit number	"777142"
transaction.cardTransactionData.settlementDate	date	Settlement date	"2025-07-23"
transaction.cardTransactionData.merchant.name	string	Merchant name	"CI Merchant"
transaction.cardTransactionData.merchant.city	string	Merchant city	"Cape Town"
transaction.cardTransactionData.merchant.countryCode	string	Country code	"ZA"
transaction.cardTransactionData.amount.amount	number	Transaction amount in minor units	1600
transaction.cardTransactionData.amount.currencyCode	string	Currency code	"ZAR"
transaction.cardTransactionData.amount.displayValue	string	Display amount	"R16.00"
transaction.cardTransactionData.card.maskedPan	string	Masked PAN	"541333******0036"
transaction.cardTransactionData.card.binNumber	string	Bank ID Number	"541333"
transaction.cardTransactionData.card.scheme	string	Card scheme	"Mastercard"
transaction.cardTransactionData.card.cardholderName	string	Cardholder name	""
transaction.cardTransactionData.card.expiryYear	string	Expiry year	"25"
transaction.cardTransactionData.card.expiryMonth	string	Expiry month	"12"
transaction.cardTransactionData.card.countryCode	string	Issuer country code	"ZA"
transaction.cardTransactionData.mid	string	Merchant ID	"000000001328"
transaction.cardTransactionData.tid	string	Terminal ID	"00001471"
transaction.cardTransactionData.approvalCode	string	Authorization code	"421861"
transaction.paymentMethod	string	Payment method used	"card"

Capture

When a preauthorized transaction needs to be finalised, the following capture flow and payload is applicable.

Payloads

Pre-auth Capture Request

Endpoint:

POST https://api.exipay.com/v/1/transactions/<transaction-id>/capture

Headers:

Content-Type: application/json
x-api-key: <your API key>
x-exi-auth-ver: V1
x-tenant-id: <your tenant ID>

Request Body:

{
  "referenceId": "74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d",
  "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,
    "currencyCode": "ZAR"
  }
}

Field	Type	Description	Example
`referenceId`	string	Unique identifier for this transaction	`"74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d"`
`payerInformation.payerId`	string	Internal ID of the payer within the tenant’s system	`"546789"`
`payerInformation.fullName`	string	Full name of the payer	`"Test Payer"`
`payerInformation.accountCreatedDate`	date	Account creation date (format: YYYY-MM-DD)	`"2019-12-01"`
`payerInformation.email`	string	Email address of the payer	`"test@example.com"`
`payerInformation.mobileNumber`	string	Mobile number of the payer	`"0723145675"`
`payerInformation.identifyingDocument.identityDocument.country`	string	Country code of the ID document (ISO 3166-1 alpha-2)	`"ZA"`
`payerInformation.identifyingDocument.identityDocument.number`	string	National identity document number	`"5306075800082"`
`amount.amount`	number	Amount to be charged (in minor currency units, e.g. cents)	`5000`
`amount.currencyCode`	string	Currency code (ISO 4217 format)	`"ZAR"`

Response Body:

{
    "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",
        "accountType": {
          "value": 0,
          "description": "Default"
        },
        "terminalVerificationResult": "0000008001",
        "productType": "CREDIT",
        "countryCode": "ZA"
      },
      "mid": "000000001328",
      "tid": "00001471",
      "approvalCode": "421861"
    },
    "transactionTime": "2025-07-23T07:06:09.623172Z",
    "paymentMethod": "card"
  }

See the webhook payload table in the webhook pre-auth payload definition for more information on these fields.

Webhook

{
  "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",
    "externalSerialNumber": "",
    "manufacturer": "Sunmi",
    "model": "P2 Mini",
    "firmwareVersions": {
      "firmwareVersion": "x.y"
    },
    "batteryPercent": 50
  },
  "transaction": {
    "transactionId": "d5aa4c31-4cd9-410b-b20e-bff5a735e4b0",
    "referenceId": "74026ed3-f7f4-4f95-bb59-f6bfb0d9b16d",
    "transactionResult": "authorized_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",
        "otherAmount": 800,
        "otherAmountDisplayValue": "R8.00"
      },
      "card": {
        "maskedPan": "541333******0036",
        "binNumber": "541333",
        "scheme": "Mastercard",
        "cardholderName": "",
        "expiryYear": "25",
        "expiryMonth": "12",
        "accountType": {
          "value": 0,
          "description": "Default"
        },
        "productType": "CREDIT",
        "countryCode": "ZA",
      },
      "mid": "000000001328",
      "tid": "00001471",
      "approvalCode": "421861"
    },
    "transactionTime": "2025-07-23T07:06:09.623172",
    "paymentMethod": "card"
  }
}

Integration Flow​

Payloads​

Preauthorization Initiation Request​

Webhooks​

Capture​

Payloads​

Pre-auth Capture Request​

Integration Flow

Payloads

Preauthorization Initiation Request

Webhooks

Capture

Payloads

Pre-auth Capture Request