Webhooks Overview
Receive real-time status updates from Payzava
Payzava sends webhook callbacks to your server whenever a payment, payout, or refund status changes.
When callbacks are sent
Payzava sends a POST request to your callback_url whenever the
status of a transaction changes. This happens for:
- Payment status changes (e.g.,
Processing→Completed) - Payout status changes
- Refund status changes
Callback format
Callbacks are sent as a POST request to your callback_url with
status information passed as query parameters:
POST https://yourserver.com/webhooks/payzava?transactionId=txn_abc123&status=Completed&amount=500&description=Order%20%2367890¬e=Premium%20plan
Query parameters
| Parameter | Description |
|---|---|
transactionId | The transaction/payout/refund ID |
status | The new status value |
amount | The transaction/payout amount |
description | The description provided when the payment was created (payment callbacks only) |
note | The note provided when the payment was created, if any (payment callbacks only, omitted if not set) |
Notes:
amountis included in both Payment and Payout callbacks.descriptionandnoteare included in Payment callbacks only — Payout callbacks do not currently include these fields.noteis only present in the callback URL if a note was provided at creation time. If no note was set, the parameter is omitted entirely.
Full callback examples
Payment callback (with note):
https://yourserver.com/webhooks/payzava?transactionId=txn_abc123&status=Completed&amount=500&description=Order%20%2367890¬e=Premium%20plan
Payment callback (without note — note omitted when not set):
https://yourserver.com/webhooks/payzava?transactionId=txn_abc123&status=Cancelled&amount=250&description=Order%20%2312345
Status values
| Status | Description |
|---|---|
Processing | Transaction is being processed |
Completed | Transaction was successful |
Cancelled | Transaction was cancelled or failed |
Responding to callbacks
You must respond with a 200 OK status code within 5 seconds.
If your server does not respond in time, the callback will time out.
HTTP/1.1 200 OK
Callbacks may fire multiple times
Payzava may send the same callback more than once. Your callback handler must be idempotent — processing the same callback twice should not cause duplicate actions.
Recommended pattern
- Receive the callback
- Respond with
200 OKimmediately - Call the retrieve endpoint to verify the current status
- Process the status change based on the retrieve response
Callback timeout
The callback timeout is 10 seconds. If your server does not respond within this window, the callback is considered failed.
Important
Note:
A failed callback does not affect the actual transaction. The payment, payout, or refund will still proceed normally. Always verify status via the retrieve endpoint.