Skip to main content

Webhooks

Webhooks are how every API in this reference calls back to your system — not a fifth product alongside Payments, Debit Order, AVS and Wallet. For the server URL, authentication and the JSON Web Token you send on each call to the platform, see Getting started; this page covers the JSON Web Token the platform sends to you on a post-back.

Introduction​

The Webhook provides for the following use cases:

  • Payment Notification
  • Topup Notification

Available APIs:

  • Wallet API for transactional information and Wallet Balance updates
  • AVS API for account Verification Services
  • Debit order API for Debit Order Services
  • Payments API for Payment Services

Settings​

Configure the webhook under Setup > General Settings > API Settings, by selecting the Access Token.

  • Payments Post-back URL is your full URL for notifications, e.g. https://your-url.co.za/postback
  • Notifications to Post — Payment Result and/or Top-up
  • Post-back Content Type — JSON or URL Encoded

Notifications to post​

Notifications to Post is for payment results, and/or account top-up notifications.

Note: Both are sent to the same URL. Distinction is to be made in the payload for notification_type as payment or topup.

Payment Notification​

Example pending — this example could not be reconstructed reliably from the source document and is being prepared.

Top-up​

{
"notification_type": "topup",
"date": "2026-01-21",
"description": "Electronic deposit -inv01234",
"amount": "300"
}

JSON Web Tokens​

Should the JWT Secret be stored in API settings, with a 32 to 64 character string, a JWT will be sent in the HTTP header as the authorization bearer.

The JWT will consist of the following:

  • Issuer (iss): the gateway issuing the token
  • Audience (aud): the intended recipient
  • Issued At (iat): the Unix timestamp when the token was created
  • JWT ID (jti): a unique onetime use identifier for the token. This is to enhance security.

Token Example

{
"iss": "issuing_host.com",
"aud": "receiving_host.com",
"iat": 1771403142,
"jti": "69957786c5b4e"
}

If no secret is stored with API settings, then no JWT will be included in the post.