Skip to main content

Transaction Webhooks

Stitch will post one or more transaction webhooks per transaction throughout the transaction life cycle. The sections below provide a breakdown of the different scenarios.

See Transaction webhook definition for the transaction webhook payload. Take special note of the enum options for transaction.transactionResult in order to implement transaction state management in the webhook consumer as described in the Webhook Introduction section.

Approved Charge​

For an approved transaction, two webhooks will be received:

  • In the first webhook, the transaction.transactionResult will be approved, indicating the acquirer has approved the transaction.
  • In the second webhook, the transaction.transactionResult will be approved_confirmed, indicating the terminal has received the approved response and the transaction is now complete.

Declined Charge​

For a declined transaction, there would be a maximum of two webhooks sent:

  • In the first webhook, the transaction.transactionResult will be declined, and in general this will be the last webhook sent for declined transactions.
  • In the second webhook, which occurs infrequently, the declined transaction may be reversed. For some acquirer routes, a declined transaction may temporarily reserve cardholder funds. Stitch will determine in which cases declines may reserve funds and in these cases attempt a reversal. Should the reversal succeed, a second webhook with transaction.transactionResult of reversed will be sent.

Failed Charge​

A failed transaction means that the Stitch platform could not successfully send the request upstream to the acquirer for technical reasons (e.g., no network connectivity upstream, the acquirer times out, etc.).

For a failed transaction, there would be a maximum of two webhooks sent:

  1. In the first webhook, the transaction.transactionResult will be failed, and in general this will be the last webhook sent for failed transactions.
  2. In the second webhook, which occurs infrequently, the failed transaction may be reversed. For some acquirer routes, a failed transaction may temporarily reserve cardholder funds. Stitch will determine in which cases failures may reserve funds and in these cases attempt a reversal. Should the reversal succeed, a second webhook with transaction.transactionResult of reversed will be sent.

Reversed Charge​

Reversed by Terminal​

This can happen when the EMV chip on the card rejects the acquirer response.

For a reversed transaction, two webhooks will be received:

  • In the first webhook, the transaction.transactionResult will be approved, indicating the acquirer has approved the transaction.
  • In the second webhook, the transaction.transactionResult will be reversed.

Reversed by Stitch Platform​

After a transaction has been approved, something can prevent the terminal from getting the response (a network issue, the terminal battery dies, or the app crashes).

In these cases, Stitch will reverse the transaction.

For a reversed transaction, you will receive two webhooks:

  • In the first webhook, the transaction.transactionResult will be approved, indicating the acquirer has approved the transaction.
  • In the second webhook, the transaction.transactionResult will be reversed. This will be received one to five minutes after the charge request.

Void​

Transactions can be voided from the terminal app (if the feature is supported) or from the Stitch backend. The void can be requested either via a support email (support@exipay.co.za) or via a B2B API integration available to directly integrate into the Stitch void API.

A transaction can only be voided if the void instruction is sent before batch cutover for the day. The transaction webhook as well as transaction lookup has an attribute (voidableUntilTime) to indicate until when a void instruction can be accepted (see Void).

A void is essentially a reversal instruction, the difference being that the transaction.transactionResult at the end will be voided (as opposed to reversed).

Single TAP & PIN​

For supporting terminals, a contactless transaction may result in a decline with code 65. Instead of requiring a new contact transaction, the terminal can prompt the cardholder for a PIN.

This flow is a combination of declined charge & approved charge, but the transaction.referenceId will be the same.

  • In the first webhook, the transaction.transactionResult will be declined. This is the first transaction and will prompt the cardholder to input their PIN.
  • In the second webhook, the transaction.transactionResult will be approved. This is the second transaction (assuming the PIN was correct) and it has the same transaction.referenceId as the first webhook and also contains a transaction.originalTransactionId linking it to the first transaction.
  • In the third webhook, the transaction.transactionResult will be approved_confirmed. This is sent once the terminal approves the second transaction. It contains the same transaction.referenceId and transaction.originalTransactionId as above.