Webhooks

Applies to:Merchants with API integration

Webhooks allow you to receive real-time notifications about events in your ZAFA PAY account. Instead of polling the API, you can configure endpoint URLs that will receive HTTP POST requests when events occur.

Overview

When an event occurs (e.g., a payment succeeds or a refund is processed), ZAFA PAY sends a JSON payload to each webhook endpoint you have configured for that event type. Your server should return a 2xx status code to acknowledge receipt.

Webhooks are managed from the Webhooks tab in your Merchant Portal settings.

Add a webhook endpoint

To start receiving webhook notifications, add an endpoint:

1Log in to the Merchant Portal and go to Merchant Settings.
2Click the Webhooks tab.
3Click Add Endpoint.
4Enter your endpoint URL. This must be a publicly accessible HTTPS URL that can receive POST requests.
5Select the event types you want to subscribe to (see the event types section below).
6Click Create to save the endpoint.
7Your webhook secret will be displayed. Copy it immediately — it will only be shown once.

Event types

ZAFA PAY supports the following webhook event types:

`payment.succeeded`

Triggered when a payment is successfully captured. Use this to fulfill orders or update your system.

`payment.failed`

Triggered when a payment attempt fails. Useful for logging failed attempts or notifying customers.

`payment.refunded`

Triggered when a full or partial refund is processed on a transaction.

`payment.chargeback`

Triggered when a chargeback (dispute) is opened on a transaction by the cardholder's bank.

`payout.completed`

Triggered when a settlement payout to your bank account has been completed.

Tip

You can subscribe to different event types per endpoint. For example, you might send payment events to your order system and payout events to your accounting system.

Webhook secret

Each webhook endpoint is assigned a unique secret when it is created. Use this secret to verify that incoming requests are genuinely from ZAFA PAY by validating the request signature.

Important

The webhook secret is displayed only once at the time of creation. If you lose it, you will need to delete the endpoint and create a new one to receive a new secret.

Store the secret securely on your server (e.g., in environment variables) and use it to verify each incoming webhook request. Never expose the secret in client-side code.

Edit and delete endpoints

You can modify or remove webhook endpoints at any time:

Edit: Click on an existing endpoint to change its URL or update the subscribed event types. The webhook secret remains the same when editing.
Delete: Click the delete button on the endpoint you want to remove. Deleted endpoints will immediately stop receiving notifications.

Limits and requirements

Please note the following limits when configuring webhooks:

1Maximum endpoints: You can configure up to 16 webhook endpoints per merchant account.
2HTTPS required: All endpoint URLs must use HTTPS. HTTP URLs are not accepted.
3Response timeout: Your server must respond within a reasonable time. If the endpoint consistently fails to respond, it may be temporarily disabled.

For technical assistance with webhook integration, please contact our support team.

Help Center