Integrating In-person Payments with Over the AIR API
In-person payments are easily initiated with the Stitch OTA (Over the AIR) API. This method allows for the merchant to initiate a transaction from their back end system and route to the Stitch terminal of their choosing. The Stitch Payment App will then handle the card acceptance flow on the terminal and once the payment has been completed a webhook will be returned to the merchant backend.
Initiating a Transaction
To initiate a transaction the merchant must use an API key provided by Stitch. A typical initiate transaction call is shown below:
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>
- Standard Transaction
- Pre-Auth Transaction
{
"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": "5306075800082"
}
}
},
"amount": {
"amount": 5000,
"currencyCode": "ZAR"
},
"extendedTransactionType": "none",
"posData": {
"tipAmount": "500"
}
}
{
"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": "pre_authorization",
"posData": {
"tipAmount": "500"
}
}
See REST API for details on the above fields.
referenceId
This is a unique reference per merchant for the transaction.extendedTransactionType
Indicates to the Stitch Payment App if the transaction should be processed with any special requirements i.e.pre_authorization
.posData
Is a map object that a merchant can use to provide any reference data that may be useful to be passed back to their system in a webhook.
Payer information
The payerInformation
object should be specified with information of the payer on your system's records. The set of provided information is used to increase the efficacy of fraud risk checks done by Stitch. All possible inputs may be found found in the API reference.
At a minimum, the payerId
should always be specified within a request. This may be any internal identifier that always uniquely identifies users across Stitch requests.
Extended Transaction Type
Indicates to the Stitch Payment App if the transaction should be processed with any special requirements. The current options are:
Type | Description |
---|---|
none | The transaction should be processed as a standard card transaction. |
pre_authorization | The transaction should be processed as a Pre‑Auth transaction and should be captured later. |
Handling Transaction Responses
After initiating a transaction, you will receive a unique transactionId
.
{
"transactionId": "1e40c500-20a7-442b-b35e-35d5c3fac0d4"
}
See REST API for details on the above fields.
If subscribed to receive webhooks, a number of webhooks will be submitted to the merchant indicating the current status of the transaction. The transactionId
above can be used to correlate these webhooks to the transaction initiated above.
Capturing a Transaction
A Pre-Auth transaction will not be settled until it is captured. Once captured a webhook will be submitted to the merchant indicating the result of the capture.
A Pre-Auth that has not been captured 30 days after the original authorization was requested will be automatically reversed as per scheme requirements.
Below is the required information to process the capture.
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": "5306075800082"
}
}
}
}
See REST API for details on the above fields.
amount
must be less than or equal to the original authorization amount.
Voiding a Transaction
On the Transaction Webhook the voidableUntilTime
indicates until when the transaction can be voided. The transactionId
attribute in the webhook should be used as the url parameter to request the void.
Below is the required information to process the void.
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"
}
}
See REST API for details on the above fields.
Refunding a Transaction
On the Transaction Webhook, cardNotPresentRefundableStatus
indicates whether the refund will be processed by the acquirer. Possible values are unknown
, refundable
, and not_refundable
. A refund attempt can be made regardless of this status, but not_refundable
is likely to be declined due to issuer policy. unknown
indicates a tokenised card or insufficient card data to determine refundability.
- Refunds are allowed up to 180 days after transaction.
- Multiple refunds are allowed against a debit.
- A refund will only be processed if the total refunded amount is less than or equal to the original debit.
- The ability to void a refund is not currently available
- If a refund has been approved, then a void will no longer be allowed.
Below is the required information to process the refund.
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
}
referenceId
This is a unique reference per merchant for the transaction.amount
Indicates how much to refund for the transaction. If not provided the entire original transaction amount will be refunded.
See REST API for details on the above fields.