PayZu GatewayWebhooks

Modelo de evento


Nesta páginaCorpo do avisoExemplo de corpoRegras do corpo

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":{ … }}}
CampoTipoDescrição
idstringIdentificador do evento, o mesmo em todas as tentativas, no reenvio e em todos os webhooks que recebem o evento.
typestringNome do evento, igual ao cabeçalho X-Webhook-Event.
created_atstringData e hora do evento, em ISO 8601 UTC.
dataobjetoO 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 dataEventosMesmo formato de
invoiceinvoice.*Consultar uma fatura, com payments e refunds
subscriptionsubscription.*Consultar uma assinatura
chargebackchargeback.*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.created e invoice.paid. Na criação da assinatura, saem subscription.created e invoice.created antes da cobrança e, com o cartão aprovado, invoice.paid e subscription.activated.
  • Fatura nova: invoice.created chega com a fatura pending e payments vazio. Na compra pelo link, chega com customer nulo e payment_link preenchido.
  • Assinatura nova: subscription.created chega com a assinatura incomplete. A assinatura sem plano chega com plan nulo.
  • Fatura de link com desconto: invoice.paid da fatura paga com o meio do desconto já traz amounts com 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 em data.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.