PayZu PixEventos de webhook
Transação com erro
WEBHOOKTRANSACTION_ERROR
Confira o passo a passo → https://docs.payzu.com.br/docs/pix/webhooks
Sai quando a transação passa para o status ERROR. Consulte a transação e fale com o suporte informando o id. 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_ERRORX-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.0Body
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.
DEPOSITWITHDRAWstatusstringobrigatório
ERROR: a transação terminou com erro.
ERRORmethodstringobrigatório
PIX, INTERNAL_TRANSFER (transferência entre contas PayZu), BANK_SLIP (boleto) ou TED.
PIXINTERNAL_TRANSFERBANK_SLIPTEDclientReferencestring | 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.
cpfcnpjemailphoneevpwithdrawQrCodeTextstring | 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.
PENDINGCOMPLETEDCANCELEDrefundReasonstring | 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_REQUESTrefundDescriptionstring | 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: o evento do status novo segue por conta própria, se o webhook o assinar. No callbackUrl, a nova tentativa sai com o estado atual da transação.
sem corpo
Esta página ajudou?