Event Types

Webhooks are supported for all transaction event types that Stitch offers. These include the following types:

Type	Product Usage
`payment`	For all products that incorporate payment requests, including Pay by Bank, Capitec Pay, Card (Once-off), Manual EFT and Cash. This webhook will be sent on each payment request status update.
`payment.confirmation`	For all products that incorporate payment requests, and when a Stitch intermediary account is used, including Pay by Bank, Capitec Pay, Card (Once-off), Manual EFT and Cash. This will be sent whenever funds are received for the payment request, in the intermediary account.
`payment-consent-request`	For tokenized payin products, such as Card, and Debicheck. This will be sent on all initiated consent status updates.
`transaction`	For tokenized payin products, such as Card, and Debicheck. This will be sent on all initiated transaction status updates.
`refund`	For the Refunds product. This will be sent on each refund status update.
`disbursement`	For the Disbursements product. This will be sent on each disbursement status update.
`settlement`	For the Settlements product, when a Stitch intermediary account is used for payins. This will be sent on each settlement status update.
`direct-deposit`	[Deprecated] For the Direct Deposits product, when a Stitch intermediary account is used for payins. This will be sent whenever funds are received for a direct deposit, in the intermediary account.
`payment-initiation`	[Deprecated] For the LinkPay product. This will be sent on each payment initiation status update.
`payment-initiation.confirmation`	[Deprecated] For the LinkPay product, and when a Stitch intermediary account is used. This will be sent whenever funds are received for the payment initiation, in the intermediary account.

Statuses and Example Payloads

Webhooks are typically sent when the core status of the payment / transaction type is updated. Exact status changes, as well as example payloads, indicating typical structure for the webhook type, are detailed below:

Payment

The payment webhook will be dispatched for each of the following status updates:

PaymentInitiationRequestCompleted
PaymentInitiationRequestCancelled
PaymentInitiationRequestExpired

Example Payload

{
  "data": {
    "client": {
      "paymentInitiationRequests": {
        "node": {
          "__typename": "PaymentInitiationRequest",
          "amount": {
            "currency": "ZAR",
            "quantity": "1"
          },
          "bankBeneficiaries": [
            {
              "__typename": "BankBeneficiary",
              "accountNumber": "1223273660",
              "bankAccountNumber": "1223273660",
              "bankId": "nedbank",
              "name": "FizzBuzz Co."
            }
          ],
          "beneficiaries": [
            {
              "__typename": "BankBeneficiary",
              "accountNumber": "1223273660",
              "bankAccountNumber": "1223273660",
              "bankId": "nedbank",
              "name": "FizzBuzz Co."
            }
          ],
          "beneficiaryReference": "KombuchaFizz",
          "cancellationReason": null,
          "created": "2022-10-11T09:52:13.312Z",
          "createdAt": "2022-10-11T09:52:13.312Z",
          "currency": "ZAR",
          "events": [],
          "externalReference": "79261d16-c53b-48eb-9019-dc9cfb6c5126",
          "failureReason": null,
          "id": "cGF5cmVxLzk2YjUyODU1LTBkMzQtNDI0MS04YmM2LWE4ODBlMDQ1ZGQzOQ==",
          "payerConstraints": null,
          "payerReference": "Joe-Fizz-01",
          "paymentConfirmation": {
            "__typename": "PaymentPending",
            "date": "2022-10-11T09:52:53.128Z"
          },
          "paymentMethods": [
            {
              "cash": {
                "atm": {
                  "enabled": true
                },
                "retailer": {
                  "barcodeNumber": "test-11132098754321",
                  "barcodeUrl": "https://test-barcode-url.com",
                  "enabled": true
                }
              }
            },
            {
              "eft": {
                "enabled": true
              }
            }
          ],
          "paymentRequestPayerConstraintRelationship": null,
          "quantity": "1",
          "refunds": [],
          "state": {
            "__typename": "PaymentInitiationRequestCompleted",
            "amount": {
              "currency": "ZAR",
              "quantity": 1
            },
            "beneficiary": {
              "__typename": "BankBeneficiary",
              "accountNumber": "1223273660",
              "bankAccountNumber": "1223273660",
              "bankId": "nedbank",
              "name": "FizzBuzz Co."
            },
            "date": "2022-10-11T09:52:53.114Z",
            "id": "96b52855-0d34-4241-8bc6-a880e045dd39",
            "payer": {
              "__typename": "PaymentInitiationBankAccountPayer",
              "accountName": "Current account",
              "accountNumber": "4104754941",
              "accountType": "current",
              "bankId": "absa"
            },
            "proofOfPayment": null
          },
          "updated": "2022-10-11T09:52:53.128Z",
          "updatedAt": "2022-10-11T09:52:53.128Z",
          "url": "https://secure-local.stitchmoney.com/connect/payment-request/96b52855-0d34-4241-8bc6-a880e045dd39",
          "userReference": "Joe-Fizz-01"
        }
      }
    }
  }
}

Payment Confirmation

The payment.confirmation webhook will be dispatched for each of the following status updates:

PaymentReceived
PaymentUnsettled

Example Payload

{
  "data": {
    "client": {
      "paymentInitiationRequests": {
        "node": {
          "__typename": "PaymentInitiationRequest",
          "amount": {
            "currency": "ZAR",
            "quantity": "1"
          },
          "bankBeneficiaries": [
            {
              "__typename": "BankBeneficiary",
              "accountNumber": "1223273660",
              "bankAccountNumber": "1223273660",
              "bankId": "nedbank",
              "name": "FizzBuzz Co."
            }
          ],
          "beneficiaries": [
            {
              "__typename": "BankBeneficiary",
              "accountNumber": "1223273660",
              "bankAccountNumber": "1223273660",
              "bankId": "nedbank",
              "name": "FizzBuzz Co."
            }
          ],
          "beneficiaryReference": "KombuchaFizz",
          "cancellationReason": null,
          "created": "2022-10-11T09:52:13.312Z",
          "createdAt": "2022-10-11T09:52:13.312Z",
          "currency": "ZAR",
          "events": [],
          "externalReference": "79261d16-c53b-48eb-9019-dc9cfb6c5126",
          "failureReason": null,
          "id": "cGF5cmVxLzk2YjUyODU1LTBkMzQtNDI0MS04YmM2LWE4ODBlMDQ1ZGQzOQ==",
          "payerConstraints": null,
          "payerReference": "Joe-Fizz-01",
          "paymentConfirmation": {
            "__typename": "PaymentReceived",
            "date": "2022-10-11T10:47:13.283Z",
            "estimatedSettlement": "2022-10-11T10:47:13.283Z",
            "received": "2022-10-11T10:47:13.283Z"
          },
          "paymentMethods": [
            {
              "cash": {
                "atm": {
                  "enabled": true
                }
              }
            },
            {
              "eft": {
                "enabled": true
              }
            }
          ],
          "paymentRequestPayerConstraintRelationship": null,
          "quantity": "1",
          "refunds": [],
          "state": {
            "__typename": "PaymentInitiationRequestCompleted",
            "amount": {
              "currency": "ZAR",
              "quantity": 1
            },
            "beneficiary": {
              "__typename": "BankBeneficiary",
              "accountNumber": "1223273660",
              "bankAccountNumber": "1223273660",
              "bankId": "nedbank",
              "name": "FizzBuzz Co."
            },
            "date": "2022-10-11T09:52:53.114Z",
            "id": "96b52855-0d34-4241-8bc6-a880e045dd39",
            "payer": {
              "__typename": "PaymentInitiationBankAccountPayer",
              "accountName": "Current account",
              "accountNumber": "4104754941",
              "accountType": "current",
              "bankId": "absa"
            },
            "proofOfPayment": null
          },
          "updated": "2022-10-11T09:52:53.128Z",
          "updatedAt": "2022-10-11T09:52:53.128Z",
          "url": "https://secure-local.stitchmoney.com/connect/payment-request/96b52855-0d34-4241-8bc6-a880e045dd39",
          "userReference": "Joe-Fizz-01"
        }
      }
    }
  }
}

The payment-consent-request webhook will be dispatched for each of the following status updates:

PaymentConsentProcessing
PaymentConsentFailed
PaymentConsentGranted
PaymentConsentCancelled
PaymentConsentExpired
PaymentConsentRevoked

Example Debicheck Payload

{
  "datetime": "2023-05-10T12:22:42.865Z",
  "id": "consent-request:status:success:cb6f2bd9-5c88-41f9-82a5-a45a24610bf6",
  "type": "consent-request-status"
  "data": {
    "createdAt": "2023-06-11T11:52:49.230Z",
    "id": "cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
    "status": "GRANTED",
    "type": "DEBICHECK",
    "updatedAt": "2023-06-21T11:52:49.230Z"
  }
}

Example Card Payload

{
  "data": {
    "card": {
      "cardHolderName": "Joe Soap",
      "expiryMonth": 12,
      "expiryYear": 25,
      "first6": "555550",
      "id": "Y2FyZC85YWY4OGE4MS05ZjNhLTRlNDItYWRiYy04ZTA1M2Q1YTM3M2U=",
      "last4": "0331",
      "network": "Mastercard"
    },
    "createdAt": "2023-06-11T11:52:49.230Z",
    "id": "cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
    "status": "GRANTED",
    "type": "CARD",
    "updatedAt": "2023-06-21T11:52:49.230Z"
  },
  "datetime": "2023-05-10T12:22:42.865Z",
  "id": "consent-request:status:success:cb6f2bd9-5c88-41f9-82a5-a45a24610bf6",
  "type": "consent-request-status"
}

Example CapitecPay VRP Payload

{
  "data": {
    "createdAt": "2023-06-11T11:52:49.230Z",
    "id": "cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
    "status": "granted",
    "type": "capitecpay",
    "updatedAt": "2023-06-21T11:52:49.230Z"
  },
  "datetime": "2023-05-10T12:22:42.865Z",
  "id": "consent-request:status:success:cb6f2bd9-5c88-41f9-82a5-a45a24610bf6",
  "type": "consent-request-status"
}

Transaction

The transaction webhook will be dispatched for each of the following status updates:

TransactionSuccess
TransactionFailure

Example Payload

{
  "data": {
    "amount": {
      "currency": "ZAR",
      "quantity": "1"
    },
    "card": {
      "cardHolderName": "Joe Soap",
      "expiryMonth": 12,
      "expiryYear": 2024,
      "first6": "41111111",
      "id": "Y2FyZC85YWY4OGE4MS05ZjNhLTRlNDItYWRiYy04ZTA1M2Q1YTM3M2U=",
      "last4": "1111",
      "network": "Visa"
    },
    "createdAt": "2023-05-10T12:22:42.865Z",
    "externalReference": "79261d16-c53b-48eb-9019-dc9cfb6c5126",
    "id": "Y2FyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "originalAmount": {
      "currency": "ZAR",
      "quantity": "1"
    },
    "originalTransactionId": "GBFyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw",
    "paymentConsentRequestId": "FRFyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "paymentRequestId": "RRFyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "status": "success",
    "statusReason": null,
    "type": "card",
    "updatedAt": "2023-05-10T12:22:42.865Z"
  },
  "datetime": "2023-05-10T12:22:42.865Z",
  "id": "transaction:status:success:40431E69-3DF7-4B2A-B464-DE540474BC1C",
  "type": "transaction"
}

Refund

The refund webhook will be dispatched for each of the following status updates:

RefundSubmitted
RefundCompleted
RefundError
RefundPaused

Example Payload

{
  "data": {
    "client": {
      "refunds": {
        "node": {
          "__typename": "Refund",
          "amount": {
            "currency": "ZAR",
            "quantity": "1"
          },
          "beneficiaryReference": "testing",
          "created": "2022-10-11T11:54:13.710Z",
          "id": "cmVmdW5kLzFmY2Q0N2YwLWYyMTItNGFlYy04ZjA2LTY4ZDZhYzQzZDg5Mg==",
          "nonce": "6525e472-b70b-4c38-83e9-ee6367919180",
          "paymentInitiation": null,
          "paymentInitiationRequest": {
            "__typename": "PaymentInitiationRequest",
            "amount": {
              "currency": "ZAR",
              "quantity": "1"
            },
            "bankBeneficiaries": [
              {
                "__typename": "BankBeneficiary",
                "accountNumber": "1223273660",
                "bankAccountNumber": "1223273660",
                "bankId": "nedbank",
                "name": "FizzBuzz Co."
              }
            ],
            "beneficiaries": [
              {
                "__typename": "BankBeneficiary",
                "accountNumber": "1223273660",
                "bankAccountNumber": "1223273660",
                "bankId": "nedbank",
                "name": "FizzBuzz Co."
              }
            ],
            "beneficiaryReference": "KombuchaFizz",
            "created": "2022-10-11T11:52:49.230Z",
            "createdAt": "2022-10-11T11:52:49.230Z",
            "currency": "ZAR",
            "events": [],
            "externalReference": "5596d0a6-8072-4426-ab59-38ad45ef671c",
            "id": "cGF5cmVxLzIxZmMyMWFiLTE1N2UtNGI3MC1iMDNiLTY3MDZmYTkxM2IyNw==",
            "payerConstraints": null,
            "payerReference": "Joe-Fizz-01",
            "paymentConfirmation": null,
            "quantity": "1",
            "refunds": [],
            "state": {
              "__typename": "PaymentInitiationRequestCompleted",
              "amount": {
                "currency": "ZAR",
                "quantity": 1
              },
              "beneficiary": {
                "__typename": "BankBeneficiary",
                "accountNumber": "1223273660",
                "bankAccountNumber": "1223273660",
                "bankId": "nedbank",
                "name": "FizzBuzz Co."
              },
              "date": "2022-10-11T11:53:48.466Z",
              "payer": {
                "__typename": "PaymentInitiationBankAccountPayer",
                "accountName": "FNB Premier Cheque Account",
                "accountNumber": "62120098985",
                "accountType": "current",
                "bankId": "fnb"
              },
              "proofOfPayment": null
            },
            "updated": "2022-10-11T11:53:48.478Z",
            "updatedAt": "2022-10-11T11:53:48.478Z",
            "url": "https://secure-local.stitchmoney.com/connect/payment-request/21fc21ab-157e-4b70-b03b-6706fa913b27",
            "userReference": "Joe-Fizz-01"
          },
          "reason": "fraudulent",
          "status": {
            "__typename": "RefundCompleted",
            "date": "2022-10-11T11:54:14.482Z",
            "expectedSettlement": "2022-10-13T11:54:14.482Z"
          }
        }
      }
    }
  }
}

Disbursement

The disbursement webhook will be dispatched for each of the following status updates:

DisbursementSubmitted
DisbursementCompleted
DisbursementError
DisbursementPaused
DisbursementCancelled
DisbursementReversed

Example Payload

{
  "data": {
    "client": {
      "disbursements": {
        "node": {
          "__typename": "Disbursement",
          "amount": {
            "currency": "ZAR",
            "quantity": "1"
          },
          "bankBeneficiary": {
            "__typename": "DisbursementBankBeneficiary",
            "accountHolder": "example-name",
            "accountNumber": "62741016950",
            "accountType": "savings",
            "bankId": "nedbank"
          },
          "beneficiaryReference": "example-ref",
          "created": "2022-10-06T15:03:08.436Z",
          "id": "ZGlzYnVyc2VtZW50Lzc2YTlhMjIwLWVjMGItNDJmOS04NGMzLTcyOGU4MjQ4MWVlNQ==",
          "linkedAccountId": null,
          "nonce": "bc70425a-9fa3-4db7-8e8b-93edb0b2aa23",
          "status": {
            "__typename": "DisbursementCompleted",
            "date": "2022-10-06T15:03:08.694Z",
            "expectedSettlement": "2022-10-08T15:03:08.694Z"
          }
        }
      }
    }
  }
}

Settlement

The settlement webhook will be dispatched for each of the following status updates:

SettlementSubmitted
SettlementCompleted
SettlementFailed

Example Payload

{
  "data": {
    "client": {
      "settlements": {
        "node": {
          "__typename": "Settlement",
          "amount": {
            "currency": "ZAR",
            "quantity": "1"
          },
          "destination": {
            "__typename": "BankBeneficiary",
            "bankAccountNumber": "1223273660",
            "bankId": "nedbank",
            "name": "FizzBuzz Co."
          },
          "paymentInitiation": null,
          "paymentInitiationRequest": {
            "__typename": "PaymentInitiationRequest",
            "amount": {
              "currency": "ZAR",
              "quantity": "1"
            },
            "bankBeneficiaries": [
              {
                "__typename": "BankBeneficiary",
                "accountNumber": "1223273660",
                "bankAccountNumber": "1223273660",
                "bankId": "nedbank",
                "name": "FizzBuzz Co."
              }
            ],
            "beneficiaries": [
              {
                "__typename": "BankBeneficiary",
                "accountNumber": "1223273660",
                "bankAccountNumber": "1223273660",
                "bankId": "nedbank",
                "name": "FizzBuzz Co."
              }
            ],
            "beneficiaryReference": "KombuchaFizz",
            "created": "2022-10-11T11:52:49.230Z",
            "createdAt": "2022-10-11T11:52:49.230Z",
            "currency": "ZAR",
            "events": [],
            "externalReference": "5596d0a6-8072-4426-ab59-38ad45ef671c",
            "id": "cGF5cmVxLzIxZmMyMWFiLTE1N2UtNGI3MC1iMDNiLTY3MDZmYTkxM2IyNw==",
            "payerConstraints": null,
            "payerReference": "Joe-Fizz-01",
            "paymentConfirmation": null,
            "quantity": "1",
            "refunds": [],
            "state": {
              "__typename": "PaymentInitiationRequestCompleted",
              "amount": {
                "currency": "ZAR",
                "quantity": 1
              },
              "beneficiary": {
                "__typename": "BankBeneficiary",
                "accountNumber": "1223273660",
                "bankAccountNumber": "1223273660",
                "bankId": "nedbank",
                "name": "FizzBuzz Co."
              },
              "date": "2022-10-11T11:53:48.466Z",
              "payer": {
                "__typename": "PaymentInitiationBankAccountPayer",
                "accountName": "FNB Premier Cheque Account",
                "accountNumber": "62120098985",
                "accountType": "current",
                "bankId": "fnb"
              },
              "proofOfPayment": null
            },
            "updated": "2022-10-11T11:53:48.478Z",
            "updatedAt": "2022-10-11T11:53:48.478Z",
            "url": "https://secure-local.stitchmoney.com/connect/payment-request/21fc21ab-157e-4b70-b03b-6706fa913b27",
            "userReference": "Joe-Fizz-01"
          },
          "reference": "cGF5cmVxLzIxZmMyMWFiLTE1N2UtN",
          "status": {
            "__typename": "SettlementPending",
            "date": "2022-10-11T11:54:14.482Z",
            "settlementPendingReason": "Not submitted"
          }
        }
      }
    }
  }
}

Statuses and Example Payloads​

Payment​

Payment Confirmation​

Payment Consent Request​

Transaction​

Refund​

Disbursement​

Settlement​

Statuses and Example Payloads

Payment

Payment Confirmation

Payment Consent Request

Transaction

Refund

Disbursement

Settlement