PayZu PixEventos de webhook

Transação criada

WEBHOOKTRANSACTION_PENDING

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


Sai quando uma cobrança Pix ou um saque é criado e aguarda liquidação. Só os webhooks recebem: o callbackUrl não é avisado na criação.

Headers

X-Callback-Eventstringobrigatório
O evento desta entrega. A criação só é avisada aos webhooks cadastrados.TRANSACTION_PENDING
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
PENDING: a transação aguarda liquidação.PENDING
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. No saque, a tarifa é gravada depois do envio à instituição e até lá vem 0. 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: o evento do status novo segue por conta própria, se o webhook o assinar.

sem corpo

Exemploapplication/json
{  "id": "PAYZU20261118R4TZ8WD1NC004321",  "type": "DEPOSIT",  "status": "PENDING",  "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": null,  "payerDocument": null,  "payerAccountNumber": null,  "payerInstitutionIspb": null,  "payerInstitutionName": null,  "receiverName": null,  "receiverDocument": null,  "receiverInstitutionIspb": null,  "receiverInstitutionName": null,  "withdrawPixKey": null,  "withdrawPixType": null,  "withdrawQrCodeText": null,  "endToEndId": null,  "cancellationReason": null,  "paidAt": null,  "refundEndToEndId": null,  "refundAmount": null,  "refundStatus": null,  "refundReason": null,  "refundDescription": null,  "refundedAt": null,  "qrCodeBase64": null,  "createdAt": "2026-11-18T14:30:05.412Z",  "updatedAt": "2026-11-18T14:30:05.412Z",  "callbackUrl": "https://sualoja.com.br/payzu/callback",  "amount": 150,  "serviceFeeCharged": 1.05,  "receiverAccountNumber": "004321"}