PayZu PixEventos de webhook

Devolução concluída

WEBHOOKTRANSACTION_REFUNDED

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


Sai a cada devolução concluída, total ou parcial, de uma cobrança ou de um saque. Quando a soma devolvida alcança o valor da transação, o status passa a REFUNDED; antes disso, segue COMPLETED, e refundAmount traz a soma devolvida. Na callbackUrl, cada tentativa relê a transação e sai com o estado atual, então o status pode ser diferente do que o webhook cadastrado recebe.

Headers

X-Callback-Eventstring
O evento desta entrega. Só vem nas entregas aos webhooks cadastrados: o aviso ao callbackUrl sai sem este cabeçalho.TRANSACTION_REFUNDED
X-Callback-Attemptstringobrigatório
Número desta tentativa, de 1 a 12. O reenvio começa de novo em 1.
X-Callback-Signaturestring
t=<segundos Unix>, v1=<assinatura>, em que a assinatura é o HMAC-SHA256, em hexadecimal, de <t>.<corpo cru>, com o segredo do webhook ou, no callbackUrl, o segredo dos callbacks. Só vem quando o canal tem segredo, e cada tentativa sai com t novo.
User-Agentstringobrigatório
Sempre Callback-Service/1.0.Callback-Service/1.0

Body

idstringobrigatório
Identificador da transação na PayZu.
typestringobrigatório
DEPOSIT: cobrança, Pix recebido numa chave ou transferência recebida. WITHDRAW: saque ou transferência enviada.DEPOSITWITHDRAW
statusstringobrigatório
REFUNDED quando a soma devolvida alcança o valor da transação; COMPLETED antes disso.REFUNDEDCOMPLETED
methodstringobrigatório
PIX, INTERNAL_TRANSFER (transferência entre contas PayZu), BANK_SLIP (boleto) ou TED.PIXINTERNAL_TRANSFERBANK_SLIPTED
clientReferencestring | nullobrigatório
O identificador que você enviou na criação.
virtualAccountstring | nullobrigatório
A subconta virtual enviada na criação.
qrCodeTextstring | nullobrigatório
Copia e cola da cobrança criada em POST /pix. Nas demais transações vem null.
qrCodeUrlstring | nullobrigatório
Vem null no aviso. A rota da imagem sai na criação da cobrança e em GET /pix.
generatedNamestring | nullobrigatório
Nome informado para montar a cobrança.
generatedDocumentstring | nullobrigatório
CPF ou CNPJ informado para montar a cobrança.
generatedEmailstring | nullobrigatório
E-mail informado para montar a cobrança.
payerNamestring | nullobrigatório
Nome do titular da conta de origem, como a instituição informou.
payerDocumentstring | nullobrigatório
CPF ou CNPJ do titular da conta de origem.
payerAccountNumberstring | nullobrigatório
Conta PayZu de origem, quando o dinheiro sai de uma conta PayZu.
payerInstitutionIspbstring | nullobrigatório
ISPB da instituição de origem.
payerInstitutionNamestring | nullobrigatório
Nome da instituição de origem.
receiverNamestring | nullobrigatório
Nome do titular da conta de destino.
receiverDocumentstring | nullobrigatório
CPF ou CNPJ do titular da conta de destino.
receiverInstitutionIspbstring | nullobrigatório
ISPB da instituição de destino.
receiverInstitutionNamestring | nullobrigatório
Nome da instituição de destino.
withdrawPixKeystring | nullobrigatório
Chave Pix de destino do saque, já normalizada.
withdrawPixTypestring | nullobrigatório
Tipo da chave de destino. evp é a chave aleatória.cpfcnpjemailphoneevp
withdrawQrCodeTextstring | nullobrigatório
Copia e cola pago no saque por QR Code.
endToEndIdstring | nullobrigatório
Identificador fim a fim do Pix, usado na conciliação.
cancellationReasonstring | nullobrigatório
Motivo do cancelamento, em texto pronto para exibir, como Chave Pix não encontrada.
paidAtstring | nullobrigatório
Momento da liquidação, informado pela instituição.
refundEndToEndIdstring | nullobrigatório
Identificador fim a fim do Pix de devolução.
refundAmountstring | nullobrigatório
Soma devolvida até agora, em reais, como texto decimal ("30.5"). Cada aviso traz o total acumulado: converta em número para comparar, como em GET /pix, onde o campo vem como número.
refundStatusstring | nullobrigatório
Status da devolução: PENDING, COMPLETED ou CANCELED.PENDINGCOMPLETEDCANCELED
refundReasonstring | nullobrigatório
Motivo: CUSTOMER_REQUEST, pedida por você; INFRACTION, pelo MED; DENY_COMPANY_DEPOSIT, Pix pago por CNPJ numa conta que não aceita esse depósito; ADMIN_REQUEST, feita pela PayZu.CUSTOMER_REQUESTINFRACTIONDENY_COMPANY_DEPOSITADMIN_REQUEST
refundDescriptionstring | nullobrigatório
Descrição da devolução.
refundedAtstring | nullobrigatório
Momento da conclusão da devolução.
qrCodeBase64string | nullobrigatório
Vem null no aviso. A imagem sai na criação da cobrança e em GET /pix.
createdAtstringobrigatório
Criação da transação.
updatedAtstringobrigatório
Última alteração da transação. Com id, serve para deduplicar e ordenar os avisos de transação.
callbackUrlstring | nullobrigatório
A URL de aviso enviada na criação da transação.
amountnumberobrigatório
Valor da transação, em reais.
serviceFeeChargednumber
Tarifa PayZu, em reais, que pode ter mais de duas casas decimais. Pode não vir, conforme a configuração da conta.
receiverAccountNumberstring | null
Conta PayZu de destino. Não vem no saque para chave pago como transferência entre contas PayZu.

Responses

2XXQualquer status 2xx em até 5 segundos confirma a entrega. Responda direto, sem redirecionar. Outro status, falta de resposta no prazo ou resposta acima de 1 MB contam como falha, e a entrega é tentada de novo, até 12 vezes no total. Nos webhooks, a entrega cujo status já mudou quando a tentativa sai é descartada, sem nova tentativa, menos a da devolução parcial. No callbackUrl, a nova tentativa sai com o estado atual da transação.

sem corpo

Exemploapplication/json
{  "id": "PAYZU20261118R4TZ8WD1NC004321",  "type": "DEPOSIT",  "status": "REFUNDED",  "method": "PIX",  "clientReference": "pedido-4821",  "virtualAccount": null,  "qrCodeText": "00020126860014br.gov.bcb.pix2564qrcode.payzu.com.br/dynamic/11111111-2222-3333-4444-5555555555555204000053039865802BR5909PAYZUPLUS6009SAO PAULO62070503***630489B0",  "qrCodeUrl": null,  "generatedName": "Maria Souza",  "generatedDocument": "12345678909",  "generatedEmail": "maria.souza@example.com",  "payerName": "Maria Souza",  "payerDocument": "12345678909",  "payerAccountNumber": null,  "payerInstitutionIspb": "12345678",  "payerInstitutionName": "Banco Exemplo S.A.",  "receiverName": "Loja Exemplo Ltda",  "receiverDocument": "11222333000181",  "receiverInstitutionIspb": "87654321",  "receiverInstitutionName": "Instituição Exemplo S.A.",  "withdrawPixKey": null,  "withdrawPixType": null,  "withdrawQrCodeText": null,  "endToEndId": "E12345678202611181432Xb7Kp2Qm9Tz",  "cancellationReason": null,  "paidAt": "2026-11-18T14:32:41.000Z",  "refundEndToEndId": "D12345678202611181605Qw3Er5Ty7Ui",  "refundAmount": "150",  "refundStatus": "COMPLETED",  "refundReason": "CUSTOMER_REQUEST",  "refundDescription": "Pedido cancelado pelo cliente",  "refundedAt": "2026-11-18T16:05:12.000Z",  "qrCodeBase64": null,  "createdAt": "2026-11-18T14:30:05.412Z",  "updatedAt": "2026-11-18T16:05:12.340Z",  "callbackUrl": "https://sualoja.com.br/payzu/callback",  "amount": 150,  "serviceFeeCharged": 1.05,  "receiverAccountNumber": "004321"}