Devoluções de pagamento

Um pagamento devolvido é um pagamento que havia sido marcado como COMPLETED, mas foi revertido depois pelo parceiro pagador ou pela rede. Quando isso acontece, o estado do pagamento muda para RETURNED.

Os pagamentos devolvidos são diferentes dos pagamentos que falharam:

FAILED - não foi possível concluir o pagamento. Nenhum recurso foi debitado da sua conta.
RETURNED - o pagamento foi concluído inicialmente, e os recursos foram debitados e faturados. Depois, o parceiro pagador devolveu os recursos. A Ripple credita o seu saldo automaticamente, e os ajustes aparecem nas faturas e nos relatórios.

Como funcionam as devoluções de pagamento

Quem aciona as devoluções: apenas a Ripple pode iniciar uma devolução nesta primeira versão. Clientes e parceiros pagadores não podem acionar devoluções diretamente.
O que muda:
- O estado do pagamento muda para RETURNED na API de pagamentos, na interface e nos relatórios.
- Um novo registro de transição de estado é adicionado (de COMPLETED para RETURNED).
- Notificações de webhook são enviadas para o evento de devolução.
Os detalhes do erro (código do motivo, tipo, descrição, timestamp) são incluídos no campo errors[] do objeto de pagamento.

Onde os pagamentos devolvidos aparecem

API de pagamentos:

O paymentState é RETURNED.
O errors[] traz o motivo da devolução. Exemplo:

{
    "paymentId": "a9171c23-ac54-478b-92eb-5d64ac7489a2",
    "paymentState": "RETURNED",
    "errors": [
        {
        "code": "SYS_120",
        "type": "SYSTEM_ERROR",
        "title": "Bank-Initiated Return",
        "description": "The destination bank returned the funds on behalf of their customer or based on internal policy.",
        "status": 500,
        "timestamp": "2026-01-07T18:27:57.129Z"
        }
    ]
}

Interface de pagamentos: a tela de detalhes do pagamento mostra o status RETURNED e o motivo do erro associado.
Relatórios: os relatórios de remetente e de recebedor listam os pagamentos devolvidos na coluna de status.
Notificações: você recebe notificações de webhook quando um pagamento passa para RETURNED, incluindo o código do motivo e o timestamp.

Motivos de devolução

Os motivos de devolução são informados no objeto errors[] do pagamento. Eles usam o schema de erro padrão da Ripple (code, type, title, description, timestamp). Os exemplos incluem:

Exemplos:

Invalid Account Number (erro USER)
Invalid Bank Identifier (erro USER)
Compliance Reason (erro SYSTEM)
Account Frozen or Blocked (erro SYSTEM)

Observação

A lista completa de motivos de devolução pode mudar. Trate sempre os códigos desconhecidos com elegância.

Prazos

O tempo para confirmar uma devolução depende do payment rail. Por exemplo, alguns rails domésticos (como o ACH) podem levar vários dias para processar uma devolução.

Ações do cliente