PayZu PaymentsEventos de webhook

Cobrança atualizada

WEBHOOKcharge.update

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


Enviado quando o pagamento muda depois da criação: no cartão, mudança de status, estorno, resultado do antifraude ou chargeback; no Pix, pagamento, cancelamento, devolução ou falha. O mesmo estado pode chegar mais de uma vez.

Headers

X-Webhook-Signaturestringobrigatório
HMAC-SHA256, em hexadecimal, de <X-Webhook-Timestamp>.<X-Webhook-Nonce>.<corpo cru>. A chave é o segredo de assinatura da credencial, usado como texto.
X-Webhook-Timestampstringobrigatório
Instante desta tentativa, em milissegundos (Unix). Entra na assinatura.
X-Webhook-Noncestringobrigatório
Valor aleatório de 32 caracteres hexadecimais, novo em cada tentativa. Entra na assinatura.

Body

eventstringobrigatório
Evento que gerou o aviso.charge.update
dataobjectobrigatório
Cobrança como está no momento do envio, não no momento do fato.
idstringobrigatório
Identificador da cobrança.
externalIdstringobrigatório
Identificador que você enviou na criação. Nos ciclos de recorrência, o da cobrança inicial.
postbackUrlstringobrigatório
URL que recebe este aviso.
amountintegerobrigatório
Valor da cobrança, em centavos.
paymentTypestringobrigatório
Meio de pagamento: creditcard para cartão e pix para Pix.creditcardpix
customerobject | nullobrigatório
Comprador.
namestringobrigatório
Nome do comprador.
identitystring | nullobrigatório
CPF ou CNPJ do comprador, só números.
identityTypestring | nullobrigatório
Tipo do documento em identity.CPFCNPJ
emailstring | nullobrigatório
E-mail do comprador.
birthdatestring | nullobrigatório
Data de nascimento, no formato AAAA-MM-DD.
phonestring | nullobrigatório
Telefone com 55, DDD e número, só dígitos.
addressobject | nullobrigatório
Endereço de cobrança. Nulo quando não foi enviado.
streetstringobrigatório
Logradouro.
numberstringobrigatório
Número.
zipCodestringobrigatório
CEP, com 8 dígitos e sem hífen.
citystringobrigatório
Cidade.
statestringobrigatório
Estado, em 2 letras.
countrystringobrigatório
País, em 2 letras.
districtstringobrigatório
Bairro.
complementstring | nullobrigatório
Complemento.
cartarray of objectsobrigatório
Carrinho. Vazio na cobrança Pix criada sem carrinho.
namestringobrigatório
Nome do produto.
quantityintegerobrigatório
Quantidade.
skustringobrigatório
Código do produto (SKU).
unitPriceintegerobrigatório
Preço unitário, em centavos.
creditCardPaymentobject | nullobrigatório
Pagamento no cartão. Nulo na cobrança Pix.
installmentsintegerobrigatório
Número de parcelas.
authenticatebooleanobrigatório
Se a cobrança foi criada com autenticação 3DS.
currencystringobrigatório
Moeda da cobrança, em código ISO 4217, como BRL.
statusintegerobrigatório
Status da transação: 0 não concluída, 1 autorizada, 2 confirmada, 3 negada, 10 cancelada, 11 estornada, 12 aguardando a instituição e 13 cancelada por falha no processamento.012310111213
cardobject | nullobrigatório
Cartão usado na cobrança.
numberstringobrigatório
Número mascarado, com os 6 primeiros e os 4 últimos dígitos.
holderstringobrigatório
Nome do portador impresso no cartão.
expirationstringobrigatório
Validade, no formato MM/AAAA.
brandstringobrigatório
Bandeira do cartão.VisaMasterEloDinersHipercard
acquirerTransactionIdstring | nullobrigatório
Identificador da transação na adquirente.
authorizationCodestring | nullobrigatório
Código de autorização da transação.
reversedAmountinteger | nullobrigatório
Valor estornado, em centavos. Preenchido quando o estorno é pedido à PayZu, antes da confirmação.
reversedDatestring | nullobrigatório
Data do estorno.
reasonCodeintegerobrigatório
Código do motivo do resultado.
chargebacksarray of objectsobrigatório
Chargebacks da cobrança. Vazio quando não há.
numberstringobrigatório
Número do chargeback. Use nas rotas de resposta ao chargeback.
amountintegerobrigatório
Valor do chargeback, em centavos.
statusstringobrigatório
RECEIVED recebido e sem resposta, ACCEPTED acatado ou encerrado por prazo e DEFENDED contestado.RECEIVEDACCEPTEDDEFENDED
reasonCodestring | nullobrigatório
Código do motivo informado pela bandeira. Pode vir vazio ou nulo.
reasonDescriptionstring | nullobrigatório
Descrição do motivo.
issuedAtstringobrigatório
Data de emissão do chargeback.
defenseDeadlinestringobrigatório
Prazo para acatar ou contestar: dez dias corridos depois de issuedAt.
responseobject | nullobrigatório
Resposta registrada. Nulo enquanto não há resposta confirmada.
actionstringobrigatório
ACCEPT quando acatado e DEFENSE quando contestado.ACCEPTDEFENSE
reasonstring | nullobrigatório
Justificativa enviada na contestação.
disputeIdstringobrigatório
Identificador da disputa.
documentNamestring | nullobrigatório
Nome do arquivo enviado na contestação.
documentTypestring | nullobrigatório
Tipo do arquivo, como application/pdf.
documentSizeinteger | nullobrigatório
Tamanho do arquivo, em bytes.
documentHashstring | nullobrigatório
SHA-256 do arquivo, em hexadecimal.
createdAtstringobrigatório
Data da resposta.
createdAtstringobrigatório
Data em que o chargeback foi registrado na PayZu.
updatedAtstringobrigatório
Data da última atualização do chargeback.
pixPaymentobject | nullobrigatório
Pagamento Pix. Nulo na cobrança de cartão.
statusstringobrigatório
pending aguardando pagamento, paid pago, canceled cancelado, pelo vencimento do QR Code ou pelo cancelamento da venda, refunded devolvido e failed com falha.pendingpaidcanceledrefundedfailed
qrCodestring | nullobrigatório
Pix copia e cola.
expiresAtstring | nullobrigatório
Até quando o QR Code aceita pagamento.
paidAtstring | nullobrigatório
Data do pagamento.
canceledAtstring | nullobrigatório
Data do cancelamento.
endToEndIdstring | nullobrigatório
Identificador do Pix no Banco Central, preenchido depois do pagamento.
refundsarray of objectsobrigatório
Devoluções do Pix, em ordem cronológica.
idstringobrigatório
Identificador da devolução.
amountintegerobrigatório
Valor devolvido, em centavos.
statusstringobrigatório
requested pedida, confirmed concluída e failed não concluída.requestedconfirmedfailed
createdAtstringobrigatório
Data do pedido de devolução.
confirmedAtstring | nullobrigatório
Data em que a devolução foi concluída.
failedAtstring | nullobrigatório
Data em que a devolução foi dada como não concluída.
recurrenceobject | nullobrigatório
Recorrência da cobrança. Nulo na cobrança avulsa.
recurrentPaymentIdstringobrigatório
Identificador da recorrência. Use nas rotas de recorrência.
intervalstringobrigatório
Periodicidade: MONTHLY mensal, ANNUAL anual e DAILY diária, para testes.MONTHLYANNUALDAILY
statusstringobrigatório
ACTIVE ativa, INACTIVE desativada e ENDED encerrada.ACTIVEINACTIVEENDED
amountintegerobrigatório
Valor de cada ciclo, em centavos.
endDatestring | nullobrigatório
Data final, quando informada na criação.
nextRecurrencystring | nullobrigatório
Data do próximo ciclo.
recurrenceCycleinteger | nullobrigatório
Número do ciclo: 0 na cobrança que abriu a recorrência e 1 em diante nos ciclos seguintes. Nulo na cobrança avulsa.
createdAtstringobrigatório
Data de criação da cobrança.
updatedAtstringobrigatório
Data da última atualização da cobrança.

Responses

2XXQualquer 2xx em até 5 segundos confirma a entrega. Responda direto, sem redirecionar. Sem isso, o aviso volta 1 minuto, 10 minutos, 1 hora, 6 horas e 24 horas depois de cada falha e é descartado depois da quinta nova tentativa.

sem corpo

Exemploapplication/json
{  "event": "charge.update",  "data": {    "id": "0b9c4e2a-6f1d-4c8e-9a37-2d5e8f1a4b6c",    "externalId": "pedido-1235",    "postbackUrl": "https://seusite.com.br/webhooks/payzu",    "amount": 10000,    "paymentType": "pix",    "customer": {      "name": "Maria Souza",      "identity": "11144477735",      "identityType": "CPF",      "email": "maria.souza@example.com",      "birthdate": null,      "phone": null,      "address": null    },    "cart": [],    "creditCardPayment": null,    "pixPayment": {      "status": "paid",      "qrCode": "00020101021226800014br.gov.bcb.pix2558pix.example.com/qr/v2/cob/0b9c4e2a6f1d4c8e9a372d5e8f1a4b6c5204000053039865802BR5912LOJA EXEMPLO6009SAO PAULO62070503***630443D0",      "expiresAt": "2026-11-18T15:02:10.000Z",      "paidAt": "2026-11-18T14:05:38.000Z",      "canceledAt": null,      "endToEndId": "E99999999202611181405a1B2c3D4e5F",      "refunds": []    },    "recurrence": null,    "recurrenceCycle": null,    "createdAt": "2026-11-18T14:02:10.417Z",    "updatedAt": "2026-11-18T14:05:41.233Z"  }}