Webhooks - Estorno BNPL

Resumo

Após a criação de um pedido de estorno, o sistema enviará webhooks para notificar sobre os eventos do processo de reversão.

Atenção!

Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio.

Webhook de Cancelamento por Estorno

Quando o tomador realiza o pagamento do Pix de devolução gerado pelo estorno, a operação de crédito é cancelada automaticamente e o seguinte webhook é enviado:

WEBHOOK_TYPE

debt

STATUS

canceled

Webhook Body

{
    "webhook_type": "debt",
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "event_datetime": "2025-10-27T16:38:59Z",
    "data": {
        "cancel_reason": "Operacao cancelada por estorno",
        "cancel_reason_enumerator": "refund_after_payee_request"
    },
    "status": "canceled"
}

Campos do Webhook

Campo	Tipo	Descrição
webhook_type	string	Tipo do webhook: debt
key	string	Chave única da dívida (DEBT-KEY)
event_datetime	string	Data e hora do evento
status	string	Status do evento: canceled
data.cancel_reason	string	Descrição textual do motivo do cancelamento
data.cancel_reason_enumerator	string	Enumerador do motivo do cancelamento

Enumeradores de Cancelamento Relacionados a Estorno

Enumerador	Descrição
refund_after_payee_request	Estorno solicitado pelo beneficiário
manual	Operação cancelada manualmente
disbursing_error	Operação cancelada por erro durante o desembolso

---

Webhook de Liquidação de Estorno (Transaction Reversal)

Para estornos processados via o endpoint de transaction_reversal, o webhook de confirmação segue o formato abaixo:

WEBHOOK_TYPE

transaction_reversal.transaction_reversal_status_change

STATUS

paid

Webhook Body

{
    "data": {
        "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1",
        "amount": 123.45,
        "status": "paid",
        "description": "Valor de liquidação indevido",
        "reference_date": "2025-03-23",
        "fund_class_document_number": "12.345.678/0009-10",
        "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487",
        "source_account": {
            "account_digit": "7",
            "account_branch": "0001",
            "account_number": "0099999",
            "owner": {
                "name": "FUNDO DE INVESTIMENTO",
                "document_number": "12.345.678/0009-10"
            },
            "financial_institution": {
                "code": "329",
                "ispb": "32402502",
                "name": "QI Sociedade de Crédito Direto"
            }
        },
        "target_account": {
            "owner": {
                "name": "Nome fictício",
                "document_number": "111.202.188-99"
            },
            "account_digit": "0",
            "account_branch": "0001",
            "account_number": "1029490",
            "target_pix_key": "1232221",
            "financial_institution": {
                "code": "033",
                "ispb": "90400888",
                "name": "BCO SANTANDER (BRASIL) S.A."
            }
        },
        "external_key": "40054daa-c3c5-49cd-add7-858b576c5887"
    },
    "webhook_type": "transaction_reversal.transaction_reversal_status_change",
    "webhook_datetime": "2025-03-23T15:08:30Z"
}

Campos do Webhook de Transaction Reversal

Campo	Tipo	Descrição
webhook_type	string	Tipo do webhook: transaction_reversal.transaction_reversal_status_change
webhook_datetime	string	Data e hora do envio do webhook
data.transaction_reversal_key	string	Chave única do estorno
data.amount	float	Valor estornado
data.status	string	Status do estorno: paid
data.description	string	Descrição do estorno
data.reference_date	string	Data de referência do processamento
data.fund_class_key	string	Chave do fundo
data.source_account	object	Dados da conta de origem do estorno
data.target_account	object	Dados da conta de destino do estorno
data.external_key	string	Chave externa da transação estornada