PayZu's webhook system allows your application to receive real-time notifications about transaction status changes. When you create a transaction and provide a callbackUrl, our system will automatically send updates to that URL whenever there's a status change.

The URL must be accessible and open for processing requests with the following header:

Content-Type: application/json

PayZu webhooks feature a robust retry system that ensures notification delivery even in case of temporary failures. When a notification is triggered, the system makes up to 5 delivery attempts with progressively longer intervals between each attempt. This approach guarantees that temporary unavailabilities or network issues won't prevent your notifications from being delivered, providing a reliable integration experience with PayZu systems.

The intervals between attempts are randomly varied within the specified ranges, which allows for better load distribution across servers and helps avoid request peaks that could overload the system. This progressive retry strategy means you can trust that your notifications will be delivered even in case of temporary problems, without needing to implement your own retry logic.

Attempt	Interval after previous	Expected situation
1st	—	Initial send
2nd	Between 1 and 3 minutes	First failure detected
3rd	Between 2 and 6 minutes	Retry 1
4th	Between 4 and 12 minutes	Retry 2
5th	Between 8 and 24 minutes	Final retry

⚠️
Response Time Requirements
Your webhook must respond with HTTP 200 OK within 10 seconds. If the response time exceeds this limit, the system considers it a timeout and initiates the retry process.

To guarantee the integrity and security of notifications, it is strongly recommended to restrict access to your webhook URL. Only official IP addresses from the PROCESSAMENTO should be allowed to communicate with your endpoint. This prevents unauthorized access and ensures that all incoming notifications are legitimate and originate from PayZu systems.

Payload Fields

Parameter	Type	Description
id	string	Transaction ID
clientReference	string	External reference you provided
status	string	PENDING, COMPLETED, CANCELED, WAITING_FOR_REFUND, REFUNDED, EXPIRED, ERROR
amount	number	Amount in BRL
type	string	DEPOSIT, WITHDRAW
qrCodeText	string	Pix "copy-and-paste" code
qrCodeUrl	string	URL to the QR Code image
generatedName	string	Reference name
generatedDocument	string	CPF/CNPJ
generatedEmail	string	Email linked to the transaction
payerName	string	Payer name
payerDocument	string	Payer document
payerInstitutionIspb	string	Payer bank ISPB
payerInstitutionName	string	Payer bank name
serviceFeeCharged	number	Service fee charged
withdrawPixKey	string	Pix key used for withdrawal
withdrawPixType	string	cpf, cnpj, phone, email, evp
receiverName	string	Receiver name
receiverDocument	string	Receiver document
receiverInstitutionIspb	string	Receiver bank ISPB
receiverInstitutionName	string	Receiver bank name
endToEndId	string	Pix EndToEnd ID
cancellationReason	string	Reason for cancellation
paidAt	string	Paid timestamp (ISO 8601)
refundEndToEndId	string	Refund EndToEnd ID
refundAmount	string	Amount refunded
refundStatus	string	PENDING, COMPLETED, FAILED
refundReason	string	Reason for refund
refundDescription	string	Refund description
refundedAt	string	Refunded timestamp (ISO 8601)
qrCodeBase64	string	QR Code image in Base64 format
createdAt	string	Creation timestamp (ISO 8601)
updatedAt	string	Update timestamp (ISO 8601)
callbackUrl	string	The webhook URL
infractions	object	Infraction info