Webhooks
The API sends a POST request to the callbackUrl provided when creating the charge or withdrawal whenever the status changes. The body is JSON with the updated transaction data.
Instead of your system constantly asking "has it been paid yet?", PayZu calls you when something happens.
Pass callbackUrl on every creation (POST /pixPOST /withdraw
{ "amount" : 99.90 , "callbackUrl" : "https://seusite.com.br/webhooks/payzu" , "clientReference" : "order-2025-001" } The endpoint must be publicly accessible and respond with HTTP 2xx within 5 seconds , accepting:
Content-Type : application/json PayZu resends the callback up to 72 times with exponential backoff and jitter when it does not receive 2xx within 5 seconds.
Field Type Description idstring Unique identifier of the transaction at PayZu clientReferencestring External identifier you provided typestring DEPOSIT or WITHDRAWstatusstring See Transaction status amountnumber Amount in reais (BRL) serviceFeeChargednumber Fee charged
Field Type Description qrCodeTextstring Pix copy-and-paste code (EMV) qrCodeBase64string QR image in Base64 qrCodeUrlstring Public URL of the QR as PNG generatedNamestring Reference name generatedDocumentstring CPF or CNPJ generatedEmailstring Linked email
Field Type Description payerNamestring Payer's name (if available) payerDocumentstring Payer's document payerInstitutionIspbstring ISPB of the payer's institution payerInstitutionNamestring Name of the institution
Field Type Description receiverNamestring Receiver's name (if provided) receiverDocumentstring Receiver's document receiverInstitutionIspbstring ISPB of the receiver's institution receiverInstitutionNamestring Name of the institution
Field Type Description withdrawPixKeystring Pix key used in the withdrawal withdrawPixTypestring See Key types
Field Type Description createdAtstring When the transaction was created (ISO 8601) updatedAtstring Last update paidAtstring | null When it was paid (null if not yet paid) endToEndIdstring EndToEnd ID of the Pix infractionobject | undefined Present only in case of MED dispute, see Glossary
Respond fast : return 2xx in under 5s. Process heavy work in a queueIdempotência : store id + status to deduplicateUse clientReference : pass an external identifier on creationRestrict by IP : accept callbacks only from the official PayZu IP
