Skip to main content

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>
{
  "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"
  }
}

See REST API for details on the above fields.

API Input Fields
  • referenceId This is a unique reference per merchant for the transaction. This is primarily used to ensure no duplicate initiate requests are performed per reference.
  • paymentMethod Indicates to the Stitch Payment App which payment method should be applied to the transaction. Currently only card is supported.
  • type Indicates to the Stitch Payment App if the transaction should be processed with any special requirements i.e. pre_auth.
  • 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. An example key in the posData structure that could be useful is a unique reference for the transaction, this can be used to reconcile OTA requests with webhooks received.

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.

Type​

Indicates to the Stitch Payment App if the transaction should be processed with any special requirements. The current options are:

TypeDescription
saleThe transaction should be processed as a standard card transaction.
sale_with_cashbackThe transaction should be processed as a standard card transaction with an additional cashback amount.
pre_authThe transaction should be processed as a Pre‑Auth transaction and should be captured later.
refundThe transaction should be processed as a card present refund.

Handling Transaction Responses​

After initiating a transaction, you will receive a response indicating the result of the OTA request.

{
  "result": "success"
}

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.

Must be captured within 30 days

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.

Capture rules
  • 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.

Refund rules
  • 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
}
API Input Fields
  • 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.