PayZu GatewayEventos de webhook

Fatura paga

WEBHOOKinvoice.paid

Confira o passo a passo → https://docs.payzu.com.br/docs/gateway/webhooks


Sai quando a fatura passa a paid: Pix recebido ou cartão aprovado. Vale também para a fatura canceled ou expired paga depois.

Headers

X-Webhook-Eventstringobrigatório
Evento. O mesmo de type no corpo.invoice.paid
X-Webhook-Timestampstringobrigatório
Instante desta tentativa, em milissegundos (Unix). Muda a cada tentativa e entra na assinatura.
X-Webhook-Noncestringobrigatório
Valor aleatório, novo a cada tentativa. Entra na assinatura.
X-Webhook-Signaturestringobrigatório
HMAC-SHA256, em hexadecimal, de <X-Webhook-Timestamp>.<X-Webhook-Nonce>.<corpo cru>, calculado com o segredo do webhook.

Body

idstringobrigatório
ID do evento. O mesmo em todas as tentativas, no reenvio e em todos os webhooks que recebem o evento.
typestringobrigatório
Evento. O mesmo de X-Webhook-Event.invoice.paid
created_atstringobrigatório
Data e hora do evento, em UTC. Não muda na nova tentativa nem no reenvio.
dataobjectobrigatório
O recurso do evento em invoice, como estava no momento do evento.
invoiceobjectobrigatório
A fatura em paid, com a tentativa que a quitou em payments e sempre com customer.
idstringobrigatório
ID da fatura.
statusstringobrigatório
Status da fatura: paid neste evento.paid
urlstringobrigatório
Página da fatura, para o cliente pagar; paga, ela é o comprovante.
descriptionstringobrigatório
Descrição da fatura.
external_referencestring | nullobrigatório
Sua referência da fatura.
created_atstringobrigatório
Data e hora da criação.
updated_atstringobrigatório
Data e hora da última alteração.
amountsobjectobrigatório
Valores da fatura, em centavos.
subtotalintegerobrigatório
Valor antes do desconto.
discountintegerobrigatório
Desconto aplicado.
totalintegerobrigatório
Valor a pagar: o subtotal menos o desconto.
paidintegerobrigatório
Tudo o que entrou, inclusive o pagamento em duplicidade.
refundedintegerobrigatório
Tudo o que foi devolvido.
billingobjectobrigatório
Prazos e datas da fatura.
cycle_numberinteger | nullobrigatório
Ciclo da assinatura, com a adesão no ciclo 0; nulo fora de assinatura.
due_atstringobrigatório
Vencimento.
expires_atstringobrigatório
Limite para pagar.
paid_atstring | nullobrigatório
Data e hora do pagamento.
canceled_atstring | nullobrigatório
Data e hora do cancelamento.
refunded_atstring | nullobrigatório
Data e hora do estorno.
chargedback_atstring | nullobrigatório
Data e hora da contestação.
itemsarray of objectsobrigatório
Itens da fatura.
namestringobrigatório
Nome do item.
skustring | nullobrigatório
Seu código do item.
quantityintegerobrigatório
Quantidade.
unit_priceintegerobrigatório
Preço unitário, em centavos.
payment_settingsobjectobrigatório
Como a fatura pode ser paga.
accepted_methodsarray of stringsobrigatório
Meios aceitos.credit_cardpix
credit_cardobject | nullobrigatório
Regras do cartão; nulo sem cartão.
max_installmentsintegerobrigatório
Máximo de parcelas no cartão.
checkoutobjectobrigatório
Para onde a página da fatura leva o cliente.
redirect_urlstring | nullobrigatório
Para onde o cliente vai depois de pagar.
cancel_urlstring | nullobrigatório
Para onde vai quem desiste.
customerobject | nullobrigatório
Cliente; nulo na fatura sem cliente, até a primeira tentativa de pagamento na página.
idstringobrigatório
ID do cliente.
namestringobrigatório
Nome do cliente.
emailstringobrigatório
E-mail do cliente.
documentstringobrigatório
CPF ou CNPJ do cliente.
document_typestringobrigatório
Tipo do documento.cpfcnpj
subscriptionobject | nullobrigatório
Assinatura da fatura; nula fora de assinatura.
idstringobrigatório
ID da assinatura.
codestringobrigatório
Código curto da assinatura.
namestringobrigatório
Nome da assinatura.
payment_linkobject | nullobrigatório
Link de pagamento da compra; nulo fora de link.
idstringobrigatório
ID do link.
namestringobrigatório
Nome do link.
paymentsarray of objectsobrigatório
Tentativas de pagamento, da mais nova para a mais antiga.
idstringobrigatório
ID da tentativa.
statusstringobrigatório
Status da tentativa.pendingprocessingpaidfailedexpiredrefund_requestedrefundedchargedback
methodstringobrigatório
Meio de pagamento.credit_cardpix
amountintegerobrigatório
Valor da tentativa, em centavos.
created_atstringobrigatório
Data e hora da tentativa.
paid_atstring | nullobrigatório
Data e hora do pagamento.
failed_atstring | nullobrigatório
Data e hora da recusa.
failureobject | nullobrigatório
Motivo da recusa; nulo fora de failed.
stagestringobrigatório
Etapa que recusou.issuerantifraudcard_checksplitprocessing
codestringobrigatório
Código da recusa.
messagestringobrigatório
Motivo da recusa, para mostrar ao cliente.
credit_cardobject
Dados do cartão; nulo no Pix.
installmentsinteger | nullobrigatório
Parcelas.
authorization_codestring | nullobrigatório
Código de autorização; nulo sem aprovação.
cardobject | nullobrigatório
Cartão.
idstring | nullobrigatório
ID do cartão salvo; nulo quando o cartão não ficou salvo.
brandstring | nullobrigatório
Bandeira.
last_digitsstringobrigatório
Últimos 4 dígitos.
holder_namestring | nullobrigatório
Nome impresso no cartão.
pixobject
Dados do Pix; nulo no cartão.
qr_code_textstring | nullobrigatório
Pix copia e cola.
expires_atstring | nullobrigatório
Quando o QR Code vence.
end_to_end_idstring | nullobrigatório
ID do Pix no Banco Central; nulo até o pagamento.
payerobject | nullobrigatório
Quem pagou o Pix, quando informado; nulo quando não.
namestring | nullobrigatório
Nome de quem pagou.
documentstring | nullobrigatório
CPF ou CNPJ de quem pagou.
refundsarray of objectsobrigatório
Estornos, do mais novo para o mais antigo.
idstringobrigatório
ID do estorno.
statusstringobrigatório
Status do estorno.requestedconfirmedfailed
amountintegerobrigatório
Valor estornado, em centavos.
requested_atstring | nullobrigatório
Data e hora do pedido.
confirmed_atstring | nullobrigatório
Data e hora da confirmação.
failed_atstring | nullobrigatório
Data e hora da recusa.
failureobject | nullobrigatório
Vem nulo: o motivo da recusa do estorno não é registrado.
codestringobrigatório
Código da recusa.
messagestringobrigatório
Motivo da recusa.
cancellationobject | nullobrigatório
Cancelamento; nulo se a fatura não está cancelada.
reasonstringobrigatório
Motivo do cancelamento.merchant_requestsubscription_cancellation
notestring | nullobrigatório
Observação do cancelamento.
chargebackobject | nullobrigatório
Contestação; nula sem contestação.
idstringobrigatório
ID da contestação.
statusstringobrigatório
Status da contestação.receivedaccepteddefended
metadataobject | nullobrigatório
Seus dados, em chave e valor; nulo sem metadata.

Responses

2XXQualquer 2xx em até 5 segundos confirma a entrega. Redirecionamento conta como falha, e o corpo da resposta não é lido. Sem 2xx, a entrega volta a ser tentada 1 minuto, 10 minutos, 1 hora, 6 horas e 24 horas depois da tentativa anterior.

sem corpo

Exemploapplication/json
{  "id": "evt_PWdksz8FNVcjry7EMUbiqx",  "type": "invoice.paid",  "created_at": "2026-11-11T15:20:59.336Z",  "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"      }    }  }}