Notificação Transferência Pix Devolvida

(transfer.refunded)

Enviada quando uma transferência PIX é devolvida pelo destinatário, de forma integral ou parcial.

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.refunded",
        "transfer_id": "7c1e0947-620e-42fc-bdcc-efbd62dd5c66",
        "client_ref": "saque_82909",
        "amount": 10,
        "status": "refunded",
        "recipient_name": "John Doe",
        "recipient_tax_id": "33858304892",
        "pix_key": "33759504892",
        "pix_key_type": "cpf",
        "e2e_id": "E5382211620269olNsA5qf2Do",
        "failure_reason": null,
        "processed_at": "2026-01-28T15:39:35.469-03:00",
        "payer": {
            "participant_ispb": "394116",
            "account_branch": "0001",
            "account_number": "359680",
            "account_type": "TRAN",
            "document_number": "63854969650172",
            "name": "Jane Doe"
        },
        "recipient": {
            "participant_ispb": "18589120",
            "account_branch": "1",
            "account_number": "833135885",
            "account_type": "TRAN",
            "document_number": "33858304892",
            "name": "John Doe"
        },
        "refunds": [
            {
                "amount": 10.0,
                "e2e_id": "D53822116202602091150bKaAHBcWyfr"
            }
        ],
        "timestamp": "2026-01-28T15:39:35.503-03:00"
}

Descrição dos Atributos

ATRIBUTO	DESCRIÇÃO	TIPO
event (Obrigatório)	Tipo do evento: transfer.refunded	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 original da transferência, em reais	DECIMAL Maior que zero
status (Obrigatório)	Status da transferência. Nesta notificação será refunded ou partially_refunded	ENUM 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 da transferência original	STRING limite de 32 caracteres
failure_reason (Opcional)	Motivo da falha (quando cancelada)	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
recipient (Obrigatório)	Objeto de dados de quem recebeu a transferência.	OBJECT
refunds (Obrigatório)	Lista de devoluções recebidas para a transferência.	LIST
refunds.amount (Obrigatório)	Valor devolvido, em reais	DECIMAL Maior que zero
refunds.e2e_id (Obrigatório)	ID End-to-End do BACEN, da devolução	STRING limite de 32 caracteres
timestamp (Obrigatório)	Data/hora do envio da notificação (ISO 8601)	DATETIME formato datetime YYYY-mm-ddTHH:MM:ss. z

Os objetos payer e recipient seguem a mesma estrutura descrita na notificação transfer.completed.

informação

Campos dos objetos payer e recipient que não tenham valor são omitidos do JSON (a chave não é enviada). Trate todos os campos internos desses objetos como opcionais.