Webhooks

A API envia uma requisição POST para a callbackUrl informada na criação da cobrança ou saque sempre que o status muda. O corpo é JSON com os dados atualizados da transação.

O que é um webhook (callback)

Em vez do seu sistema ficar perguntando "já pagou?", a PayZu chama você quando algo acontece.

Como configurar

Passe callbackUrl em cada criação (POST /pix, POST /withdraw, etc):

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

O endpoint precisa estar acessível publicamente e responder HTTP 2xx em até 5 segundos, aceitando:

Content-Type: application/json

Sistema de retry

A PayZu reenvia o callback até 72 vezes com backoff exponencial e jitter quando não recebe 2xx em 5 segundos.

Campos enviados

Identificação

Cobrança gerada

Pagador

Recebedor

Saque por chave

Timestamps e infração

Boas práticas

• Responda rápido: devolva 2xx em menos de 5s. Processe pesado em fila
• Idempotência: armazene id + status pra deduplicar
• Use clientReference: passe identificador externo na criação
• Restrinja por IP: aceite callbacks apenas do IP oficial PayZu

Suporte