Ciclo de vida do pagamento

Esta página descreve o ciclo de vida de um pagamento no Payments Direct, detalha cada estado do pagamento e explica como descobrir o estado atual de um pagamento.

Um pagamento normalmente passa pelas seguintes fases no Payments Direct:

1. Iniciado: o processo de pagamento começa quando você envia uma requisição de pagamento que referencia uma cotação aceita. Payments Direct cria um pagamento no estado INITIATED.

2. Validando: o estado do pagamento muda para VALIDATING enquanto a plataforma executa verificações internas, como validar os dados do pagamento, conferir limites e reservar recursos do seu saldo disponível.

   • Se essas verificações forem bem-sucedidas, o pagamento segue para TRANSFERRING.
   • Se for encontrado um problema previsível e corrigível pelo usuário (por exemplo, dados inválidos ou ausentes, status da conta ou regras de compliance), o pagamento passa para o estado terminal DECLINED.
   • Se um problema inesperado da plataforma ou do sistema impedir o processamento, o pagamento passa para o estado terminal FAILED.

3. Transferindo: à medida que o pagamento percorre a rede até o beneficiário, o estado dele passa a ser TRANSFERRING. O valor do pagamento é debitado do seu saldo disponível, e a Ripple ou um parceiro downstream trabalha para concluir o pagamento.

   • Se um problema previsível e corrigível pelo usuário for descoberto nesta etapa (por exemplo, o banco de destino rejeita o pagamento por regras de compliance ou pelo status da conta), o pagamento passa para o estado terminal DECLINED.
   • Se ocorrer um erro inesperado da plataforma ou do sistema, o pagamento passa para o estado terminal FAILED.

4. Concluído: se o pagamento não entrar em DECLINED nem em FAILED nas fases anteriores e o payout network creditar o beneficiário com sucesso, o pagamento chega ao estado terminal COMPLETED. Na maioria dos casos, isso significa que o beneficiário recebeu os recursos.

5. Devolvido: em alguns casos, um pagamento que já havia chegado a COMPLETED pode ser devolvido depois por uma instituição downstream ou pelo banco do beneficiário. Quando isso acontece, o pagamento passa para o estado terminal RETURNED e os recursos voltam ao ordenante. As devoluções são geridas pela Ripple e pelos parceiros pagadores; os clientes não podem acioná-las diretamente.

O diagrama abaixo mostra uma visão simplificada de como um pagamento pode transitar entre os estados:

A seção Estados do pagamento desta página traz descrições de referência de cada estado. Para mais detalhes sobre como funcionam as devoluções e como conciliá-las, consulte Devoluções de pagamento.

O campo paymentState do objeto de pagamento indica o estado atual de um pagamento. Esta seção descreve cada valor possível e o que ele significa para o seu pagamento, incluindo o novo estado DECLINED.

Payments Direct oferece os seguintes estados de pagamento:

• DECLINED: a plataforma ou um parceiro downstream se recusou a processar o pagamento porque a requisição é inválida ou não pode ser aceita na forma atual. O problema costuma ser corrigível pelo usuário (por exemplo, ajustar dados, limites ou status da conta) e o pagamento não tem nova tentativa automática.
• FAILED: um erro inesperado da plataforma ou do sistema impede o processamento do pagamento. Esses erros não dizem respeito, em primeiro lugar, à validade da própria instrução de pagamento.
• RETURNED: o pagamento foi concluído e o beneficiário foi creditado inicialmente, mas os recursos foram devolvidos depois, resultando no estado terminal RETURNED.

Em alguns pagamentos, Payments Direct retorna metadados de execução adicionais em um campo opcional payoutExecutionDetails no objeto de pagamento. Quando presente, esse objeto inclui o payment rail utilizado, informações de tempo e referências de rastreamento específicas da rede, como IDs de transação e números de confirmação.

O campo não é retornado em todos os pagamentos. Não construa fluxos obrigatórios que dependam da presença dele. Para mais informações, consulte Detalhes de execução do payout.

Você pode verificar o estado atual de um pagamento e as transições de estado dele no Payments Direct UI ou pela API do Payments Direct.

Na interface web do Ripple Payments, abra os detalhes do pagamento que você quer inspecionar.

• A aba Detalhes do pagamento mostra a passagem do pagamento pelos estados em uma linha do tempo. Cada entrada mostra o estado e o timestamp em que o pagamento chegou a ele.
• A aba JSON do objeto de pagamento traz o objeto de pagamento completo. O campo paymentState mostra o estado atual do pagamento.

Você também pode verificar o estado do pagamento pela API de pagamentos:

• Para verificar o estado atual de um pagamento específico, chame o endpoint GET /v3/payments/{paymentId}. O corpo da resposta inclui o campo paymentState.
• Para verificar o histórico de transições de estado de um pagamento, chame o endpoint GET /v3/payments/{paymentId}/states. A resposta mostra cada estado, quando o pagamento chegou a ele e a ordem das transições ao longo do tempo.

O estado de um pagamento determina o que aconteceu com os recursos do ordenante:

Payments Direct envia uma notificação de webhook PAYMENT_STATE_TRANSITION sempre que um pagamento muda de estado. Esta é a abordagem recomendada para monitorar o andamento dos pagamentos em integrações de produção, porque elimina a necessidade de polling.

O payload do webhook segue um design “thin-plus”: inclui o paymentId e o novo paymentState, além de campos de contexto como sourceCurrency, sourceAmount, destinationCurrency, payoutAmount e beneficiaryToken.

Exemplo de payload de webhook

{
  "id": "4d3f90cf-b70f-5ff1-827a-f8aa9cf84ab9",
  "eventType": "PAYMENT_STATE_TRANSITION",
  "eventVersion": 1,
  "eventData": {
    "paymentId": "5ce2c433-a96d-48d0-8857-02637a60abf4",
    "paymentState": "COMPLETED",
    "sourceCurrency": "USD",
    "sourceAmount": 100.00,
    "destinationCurrency": "BRL",
    "payoutAmount": 518.50,
    "beneficiaryToken": "cb207125-73a7-4a94-8502-a7780f1cae78",
    "createdAt": "2026-03-01T14:20:00.000Z",
    "expiresAt": "2026-04-30T14:20:00.000Z"
  },
  "createDate": "2026-03-01T14:22:46.000Z"
}

Ao construir a lógica de integração que reage aos estados do pagamento, siga estas orientações:

• Trate todos os estados terminais explicitamente. Trate COMPLETED, FAILED, DECLINED e RETURNED como desfechos distintos, com comportamentos diferentes a jusante.
• Nos pagamentos financiados via JIT, monitore AWAITING_FUNDING. Se a sua integração usa JIT_FUNDING, acompanhe este estado e garanta que os recursos sejam transferidos antes de jitFundingExpiresAt. Um pagamento que expira em AWAITING_FUNDING exige uma nova cotação e um novo pagamento.
• Não presuma a ordem dos estados a partir dos webhooks. Use GET /v3/payments/{paymentId}/states para confirmar a sequência autoritativa se a ordem de entrega for importante.
• Em FAILED e DECLINED, busque o objeto de pagamento completo para obter os detalhes do erro antes de decidir tentar novamente.
• Implemente idempotência nos handlers de estado. Os webhooks podem ser entregues mais de uma vez. O seu handler precisa ser seguro para chamadas repetidas com o mesmo paymentId e paymentState.
• Trate estados desconhecidos com elegância. Registre e acione alertas para valores de estado inesperados, mas não descarte o evento.