Webhooks

Webhooks are merchant-wide, event-based notifications configured once at the merchant account level by Zenith. The merchant provides an HTTPS endpoint URL, and Zenith registers it against the merchant account.

Once registered, Zenith will POST JSON payloads whenever:

• A transaction status changes (e.g. Pending → Successful) across any payment method or channel.
• PayTo mandate status changes
• isSettledToMerchant status changes

Webhooks are dispatched on a scheduler/timer that evaluates states and posts updates. All payment methods and channels trigger the same webhook mechanism.

Per-transaction callbacks

If you are using the Payment Plugin and need immediate, per-transaction notifications, see Callbacks and Validation. Callbacks are plugin-only and apply to a single transaction.

Callbacks vs Webhooks

Requirements

• HTTPS POST endpoint – Must be reachable from Zenith's servers.
• Stable URL – The endpoint is configured once by Zenith; changes require contacting Zenith.

Webhook Payload Fields

Field	Type	Notes
Version	number	Payload version number.
Event	string	Event type (e.g. NEW, EDIT).
PayloadType	string	Type of payload delivered (e.g. Payment, Customer).
PaymentReference	string	Unique payment reference assigned by Zenith.
CustomerName	string	null
CustomerReference	string	Reference provided by the merchant.
PaymentStatus	number	Numeric status code.
PaymentStatusDisplay	string	Human-readable payment status.
BaseAmount	number	Base amount before fees.
FundsToMerchant	number	Net amount payable to the merchant.
CustomerFee	number	Fee charged to the customer.
MerchantFee	number	Fee charged to the merchant.
PaymentAmount	number	Total amount of the transaction.
AccountOrCardNo	string	Masked account or card number.
PaymentMethod	number	Numeric code for the payment method.
PaymentMethodDisplay	string	Human-readable payment method.
PaymentCardType	number	Numeric code for the card type.
PaymentCardTypeDisplay	string	Human-readable card type.
SubCardType	string	null
SubtCardTypeDisplay	string	null (Field name is misspelled, this is not an error in documentation)
ProcessingDateTime	string	UTC ISO-8601 datetime (yyyy-MM-ddTHH:mm:ss).
SettlementDate	string	UTC ISO-8601 date (yyyy-MM-dd).
ProcessorReference	string	Reference from the processor/gateway.
IsPaymentSettledToMerchant	boolean	Indicates if the payment has been settled.
MerchantUniquePaymentId	string	null
MerchantCode	string	Merchant identifier.
AdditionalReference	string	null
PaymentSource	number	Numeric source identifier.
PaymentSourceDispaly	string	Field name is misspelled, this is not an error in documentation
IsPaymentRecalled	boolean	Indicates if the payment has been recalled.
IsPaymentRefunded	boolean	Indicates if the payment has been refunded.

Webhook Payload Example

{
  "Version": 1,
  "Event": "New",
  "PayloadType": "Payment",
  "Payload": {
    "PaymentReference": "210768",
    "CustomerName": null,
    "CustomerReference": "1",
    "PaymentStatus": 3,
    "PaymentStatusDisplay": "Successful",
    "BaseAmount": 155.08,
    "FundsToMerchant": 155.08,
    "CustomerFee": 4,
    "MerchantFee": 0,
    "PaymentAmount": 159.08,
    "AccountOrCardNo": "411111XXXXXX1111",
    "PaymentMethod": 0,
    "PaymentMethodDisplay": "Credit / Debit Card",
    "PaymentCardType": 1,
    "PaymentCardTypeDisplay": "Visa - International Cards",
    "SubCardType": null,
    "SubtCardTypeDisplay": null,
    "ProcessingDateTime": "2025-08-27T22:08:14",
    "SettlementDate": "2025-08-28",
    "ProcessorReference": "2a41cff0e84ee15f8b42",
    "IsPaymentSettledToMerchant": false,
    "MerchantUniquePaymentId": null,
    "MerchantCode": "1337",
    "AdditionalReference": null,
    "PaymentSource": 39,
    "PaymentSourceDispaly": "Api Tokenised Payment",
    "IsPaymentRecalled": false,
    "IsPaymentRefunded": false
  }
}

Webhook Payload Updates

When a webhook for a particular payment referenced is first created and sent, the Event will be New. Any subsquent webhooks reflecting status updates to that payment will have the Event: Edit.