Notificação Transferência Pix Falhou
(transfer.failed)
Enviada quando uma transferência PIX falha.
A URL que receberá as notificações deverá ser informada através do endpoint Cadastrar/Alterar Webhook
A notificação será enviada utilizando o método POST, e espera uma resposta do tipo HTTP 200.
Segue estrutura do JSON enviado como request body:
Request Body
{
"event": "transfer.failed",
"transfer_id": "7c1e0947-620e-42fc-bdcc-efbd62dd5c66",
"client_ref": "saque_82909",
"amount": 10,
"status": "failed",
"recipient_name": "John Doe",
"recipient_tax_id": "33858304892",
"pix_key": "33759504892",
"pix_key_type": "cpf",
"e2e_id": "E5382211620269olNsA5qf2Do",
"failure_reason": "Conta destino nao encontrada",
"processed_at": "2026-01-28T15:39:35.469-03:00",
"payer": {},
"recipient": {},
"timestamp": "2026-01-28T15:39:35.503-03:00"
}
Descrição dos Atributos
| ATRIBUTO | DESCRIÇÃO | TIPO |
|---|---|---|
| event (Obrigatório) | Tipo do evento: transfer.failed | STRING limite de 100 caracteres |
| transfer_id (Obrigatório) | Código único da transferência | STRING limite de 100 caracteres |
| client_ref (Opcional) | Referência externa informada na criação | STRING limite de 100 caracteres |
| amount (Obrigatório) | Valor da transferência, em reais | DECIMAL Maior que zero |
| status (Obrigatório) | Status da transferência | ENUM pending (Transferência criada, aguardando processamento) sending (Transferência em processamento) completed (Transferência realizada com sucesso) failed(Transferência falhou) canceled(Transferência cancelada) refunded (Transferência devolvida integralmente) partially_refunded (Transferência devolvida parcialmente) |
| recipient_name (Obrigatório) | Nome do destinatário | STRING limite de 100 caracteres |
| recipient_tax_id (Obrigatório) | Documento do destinatário | STRING limite de 14 caracteres |
| pix_key (Obrigatório) | Chave PIX do destinatário | STRING limite de 100 caracteres |
| pix_key_type (Obrigatório) | Tipo da chave PIX | ENUM cpf (11 dígitos numéricos - 12345678901) cnpj (14 dígitos numéricos - 12345678000190) phone (+55 + DDD + número - +5511999998888) email (e-mail válido - pagamentos@empresa.com) evp (UUID (chave aleatória) -a1b2c3d4-e5f6-7890-abcd-1234567890ab) |
| e2e_id (Opcional) | ID End-to-End do BACEN (quando pago) | STRING limite de 32 caracteres |
| failure_reason (Opcional) | Motivo da falha (quando falhou ou cancelado) | STRING limite de 100 caracteres |
| processed_at (Opcional) | Data/hora da última atualização | STRING formato datetime YYYY-mm-ddTHH:MM:ss. z |
| payer (Obrigatório) | Objeto de dados do pagador da transferência. | OBJECT |
| payer.participant_ispb (Obrigatório) | Código do banco do pagador | STRING limite de 255 caracteres |
| payer.account_branch (Obrigatório) | Número da agência do banco do pagador | STRING limite de 255 caracteres |
| payer.account_number (Obrigatório) | Número da conta bancária do pagador | STRING limite de 255 caracteres |
| payer.account_type (Obrigatório) | Tipo de conta bancária do pagador | STRING limite de 255 caracteres |
| payer.document_number (Obrigatório) | Documento (CPM/CNPJ) do pagador | STRING limite de 255 caracteres |
| payer.name (Obrigatório) | Nome do pagador | STRING limite de 255 caracteres |
| recipient (Obrigatório) | Objeto de dados de quem recebeu a transferência. | OBJECT |
| recipient.participant_ispb (Obrigatório) | Código do banco do recebedor | STRING limite de 255 caracteres |
| recipient.account_branch (Obrigatório) | Número da agência do banco do recebedor | STRING limite de 255 caracteres |
| recipient.account_number (Obrigatório) | Número da conta bancária do recebedor | STRING limite de 255 caracteres |
| recipient.account_type (Obrigatório) | Tipo de conta bancária do recebedor | STRING limite de 255 caracteres |
| recipient.document_number (Obrigatório) | Documento (CPM/CNPJ) do recebedor | STRING limite de 255 caracteres |
| recipient.name (Obrigatório) | Nome do recebedor | STRING limite de 255 caracteres |
| timestamp (Obrigatório) | Data/hora do envio da notificação (ISO 8601) | DATETIME formato datetime YYYY-mm-ddTHH:MM:ss. z |