PayZu GatewayWebhooks
Modelo de evento
Todo aviso traz um evento só, com o recurso que mudou em data, como ele estava no momento do evento.
Corpo do aviso
A entrega de uma fatura paga no cartão chega assim, com os cabeçalhos de toda entrega:
Entrega de um webhook
POST /webhooks/payzu HTTP/1.1
Host: loja.exemplo.com.br
Content-Type: application/json
X-Webhook-Signature: 38529ba6e5715de815a35b38ed5de1c6be2159d1476fd9038ecd21fadee5e1b5
X-Webhook-Timestamp: 1794410461204
X-Webhook-Nonce: f1ce2e0e86b4b7ee801aeed8458c125b
X-Webhook-Event: invoice.paid
{"id":"evt_Wq4LmZ8xNc2VbT6yKdRh3E","type":"invoice.paid","created_at":"2026-11-11T15:20:59.337Z","data":{"invoice":{ … }}}| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador do evento, o mesmo em todas as tentativas, no reenvio e em todos os webhooks que recebem o evento. |
type | string | Nome do evento, igual ao cabeçalho X-Webhook-Event. |
created_at | string | Data e hora do evento, em ISO 8601 UTC. |
data | objeto | O recurso do evento, numa chave só, conforme a tabela abaixo. |
data tem a chave da família do evento, com o recurso inteiro, nos mesmos campos, nomes e blocos da consulta dele:
Chave de data | Eventos | Mesmo formato de |
|---|---|---|
invoice | invoice.* | Consultar uma fatura, com payments e refunds |
subscription | subscription.* | Consultar uma assinatura |
chargeback | chargeback.* | Consultar uma contestação |
Exemplo de corpo
invoice.paid de uma fatura avulsa paga no cartão
{
"id": "evt_Wq4LmZ8xNc2VbT6yKdRh3E",
"type": "invoice.paid",
"created_at": "2026-11-11T15:20:59.337Z",
"data": {
"invoice": {
"id": "in_7Kd2QmXvB9LtYc4WnRz8Hs",
"status": "paid",
"url": "https://invoice.payzu.com.br/pay/in_7Kd2QmXvB9LtYc4WnRz8Hs",
"description": "Pedido 1234",
"external_reference": "pedido-1234",
"created_at": "2026-11-11T15:20:59.333Z",
"updated_at": "2026-11-11T15:20:59.336Z",
"amounts": {
"subtotal": 15990,
"discount": 0,
"total": 15990,
"paid": 15990,
"refunded": 0
},
"billing": {
"cycle_number": null,
"due_at": "2026-11-11T15:20:59.333Z",
"expires_at": "2026-11-26T15:20:59.333Z",
"paid_at": "2026-11-11T15:20:59.335Z",
"canceled_at": null,
"refunded_at": null,
"chargedback_at": null
},
"items": [
{ "name": "Curso de fotografia", "sku": "CURSO-01", "quantity": 1, "unit_price": 15990 }
],
"payment_settings": {
"accepted_methods": ["credit_card", "pix"],
"credit_card": { "max_installments": 12 }
},
"checkout": {
"redirect_url": null,
"cancel_url": null
},
"customer": {
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"document": "52998224725",
"document_type": "cpf"
},
"subscription": null,
"payment_link": null,
"payments": [
{
"id": "pay_Nfa3VKU4p0ojE3jMQeunRD",
"status": "paid",
"method": "credit_card",
"amount": 15990,
"created_at": "2026-11-11T15:20:59.333Z",
"paid_at": "2026-11-11T15:20:59.335Z",
"failed_at": null,
"failure": null,
"credit_card": {
"installments": 1,
"authorization_code": "123456",
"card": {
"id": "card_GL2pIWf5pznF4qwg2KKd5v",
"brand": "visa",
"last_digits": "1111",
"holder_name": "MARIA SOUZA"
}
}
}
],
"refunds": [],
"cancellation": null,
"chargeback": null,
"metadata": {
"internal_id": "1234"
}
}
}
}Regras do corpo
- Momento do recurso: o recurso vem como estava no momento do evento, não como está quando o aviso chega. Para o estado atual, consulte o recurso pelo
id. - Eventos em sequência: o cartão aprovado na criação da fatura dispara
invoice.createdeinvoice.paid. Na criação da assinatura, saemsubscription.createdeinvoice.createdantes da cobrança e, com o cartão aprovado,invoice.paidesubscription.activated. - Fatura nova:
invoice.createdchega com a faturapendingepaymentsvazio. Na compra pelo link, chega comcustomernulo epayment_linkpreenchido. - Assinatura nova:
subscription.createdchega com a assinaturaincomplete. A assinatura sem plano chega complannulo. - Fatura de link com desconto:
invoice.paidda fatura paga com o meio do desconto já trazamountscom o desconto. - Cartão: o corpo nunca traz o número, o CVV nem o token do cartão.
- Valores em dinheiro: vêm em centavos.
- Ordem dos campos: pode mudar no corpo entregue. Confira a assinatura sobre os bytes recebidos.
- Evento de teste: o
ping, enviado pelo painel, traz o webhook emdata.webhook, no formato de Consultar um webhook, sem o segredo.
Uma nova tentativa ou um reenvio repete o corpo guardado na entrega.
O recurso vai como estava no momento do evento. Antes de agir, compare o created_at com o do último aviso processado ou consulte a API.