Webhooks

PayZu's webhook system sends real-time notifications about status changes for your transactions. When you create a transaction and provide a callbackUrl, our system sends updates to that URL every time the status changes.

What is a webhook (callback)

A webhook (also called a callback) is a POST request that PayZu sends to your server when something happens. Unlike the regular API (where you call PayZu), here it's the opposite: PayZu calls you.

Think of a Pix charge. You created it, displayed the QR to the customer, and now you need to know when the customer pays. Two options:

1. Polling, keep asking every X seconds "paid yet? paid yet?" (costly, slow, unnecessary).
2. Webhook, let PayZu notify you as soon as the payment arrives (instant, efficient, recommended).

How to configure

There is no separate endpoint to "register a webhook". The URL is provided on each transaction created, in the callbackUrl field of the body:

{
  "amount": 99.90,
  "callbackUrl": "https://yoursite.com/webhooks/payzu",
  "clientReference": "order-2025-001"
}

PayZu will send the callback to that URL every time that transaction changes status (PENDING → COMPLETED, COMPLETED → REFUNDED, etc).

Retry system

PayZu's webhooks have a robust retry system that ensures delivery even during temporary failures. PayZu resends up to 72 times the same callback with exponential backoff and jitter, better distributing the load and avoiding request spikes.

Security

To ensure integrity and security, restrict access to your webhook endpoint. Request PayZu Processamento's official IP from support and accept callbacks only from that origin.

Payload fields

Identification

Status and values

Generated charge (deposit)

Payer

Receiver

Withdrawal via Pix key

Settlement and refund

Timestamps

Infraction (Pix dispute)

Best practices

• Respond fast: return 2xx in under 5s. Process heavy work in queues/workers, not in the handler.
• Idempotency: store id + status to deduplicate. The same callback may arrive more than once (retries, successive changes).
• Use clientReference: pass an external identifier when creating the transaction. It returns in the callback and makes it easier to correlate with your order.
• Restrict by IP: only accept callbacks from PayZu's official IP.

Inspection and resend

The API exposes the full list of callbacks sent:

• GET /user/callbacks, paginated list
• GET /user/callbacks/{id}, details
• POST /user/callbacks/resend/{transactionId}, resend callback for a transaction
• POST /user/callbacks/resend, batch resend