# 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.


Financiamento JIT
Nos pagamentos que usam JIT funding, o ciclo de vida começa com um estado adicional antes de `INITIATED`. Depois de criado, o pagamento entra em `AWAITING_FUNDING` enquanto a Ripple aguarda o recebimento dos recursos necessários. Assim que os recursos chegam, o pagamento passa para `INITIATED` e segue o ciclo de vida padrão acima. Se o financiamento não for recebido antes do prazo, o pagamento expira. Para mais informações, consulte [Métodos de financiamento](/pt-br/products/payments-direct-2/introduction/concepts/funding-methods).

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

![Estados do pagamento](../../images/payment-flow/payment-states-rpd2.svg)

A seção [Estados do pagamento](#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](/pt-br/products/payments-direct-2/introduction/concepts/payment-returns).

## Estados do 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:

| Estado   | Descrição |
|  --- | --- |
| `QUOTED` | Uma cotação foi criada, mas você ainda não a aceitou. A cotação descreve a taxa de câmbio proposta, as tarifas e os valores de um possível pagamento. Quando você aceita a cotação e cria um pagamento, a primeira transição de estado do pagamento é de `QUOTED` para `INITIATED`. |
| `AWAITING_FUNDING` | O pagamento está aguardando o recebimento dos recursos para poder prosseguir. Este estado se aplica apenas a pagamentos que usam JIT funding. Assim que os recursos necessários chegam, o pagamento passa para `INITIATED` e segue o ciclo de vida padrão. Se os recursos não forem recebidos antes do prazo de financiamento, o pagamento expira. |
| `INITIATED` | Você, o ordenante do pagamento, iniciou um pagamento enviando uma requisição que referencia uma cotação aceita. Payments Direct cria um registro de pagamento com um identificador único e define `paymentState` como `INITIATED`. |
| `VALIDATING` | A Ripple valida os dados do pagamento e reserva recursos do seu saldo disponível. A plataforma executa verificações como validação de dados, limites, status da conta e regras de compliance. Se essas verificações forem bem-sucedidas, o pagamento passa para `TRANSFERRING`. Se a requisição for previsivelmente inválida ou violar regras de negócio, de risco ou regulatórias, o pagamento passa para `DECLINED`. Se ocorrer um erro inesperado da plataforma ou do sistema, o pagamento passa para `FAILED`. |
| `TRANSFERRING` | O pagamento está percorrendo a rede até o beneficiário final. Os recursos foram reservados ou debitados do seu saldo disponível enquanto a Ripple e os parceiros pagadores tentam concluir o pagamento. Se um parceiro ou serviço interno rejeitar o pagamento por um motivo previsível e corrigível pelo usuário, o pagamento passa para `DECLINED`. Se um erro inesperado da plataforma ou do sistema impedir a conclusão, o pagamento passa para `FAILED`. |
| `DECLINED` | O pagamento foi recusado porque a instrução de pagamento não é aceitável na forma atual. As causas típicas incluem dados inválidos ou ausentes, problemas de status ou de limite da conta, questões de autorização ou regras regulatórias e de compliance aplicadas pela Ripple ou por um parceiro downstream. O pagamento não será concluído nem tem nova tentativa automática. Os recursos reservados são liberados de volta ao saldo disponível do ordenante. Para prosseguir, corrija o problema descrito na mensagem de erro e envie um novo pagamento. |
| `COMPLETED` | O pagamento foi processado com sucesso e o beneficiário foi creditado conforme a cotação acordada. Este é um estado terminal para pagamentos concluídos com sucesso. |
| `FAILED` | Não foi possível concluir o pagamento por causa de um erro inesperado da plataforma, do sistema ou da rede que a Ripple não classifica como recusa previsível. O motivo da falha, quando disponível, é retornado nos detalhes do erro. Os recursos reservados para o pagamento são liberados e devolvidos ao saldo disponível do ordenante, quando aplicável. |
| `RETURNED` | O pagamento havia sido marcado como `COMPLETED`, mas foi devolvido depois por uma instituição downstream (por exemplo, o banco do beneficiário) após o beneficiário ter sido creditado inicialmente. Este é um estado terminal. Os recursos voltam ao ordenante, e a devolução fica visível nos seus relatórios e notificações de pagamento. Os clientes não podem acionar devoluções diretamente. |


### Como o `DECLINED` se diferencia de `FAILED` e `RETURNED`

- **`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`.


## Detalhes de execução do payout

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](/pt-br/products/payments-direct-2/introduction/concepts/payment-execution-details).

## Como verificar o estado do pagamento

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.

### No Payments Direct UI

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.


### Usando a API do Payments Direct

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 /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.


## Como os recursos são afetados em cada estado

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

| Estado | Situação dos recursos |
|  --- | --- |
| `AWAITING_FUNDING` | Nenhum recurso reservado ainda. O pagamento aguarda a chegada dos recursos JIT na sua conta de ledger da Ripple. |
| `INITIATED` | Nenhum recurso reservado ainda. O pagamento foi enviado, mas ainda não foi validado. |
| `VALIDATING` | Os recursos são **reservados** do saldo disponível. O ordenante não pode usar recursos reservados em outros pagamentos. |
| `TRANSFERRING` | Os recursos são **debitados**. O pagamento está em andamento; o valor de origem saiu da conta do ordenante. |
| `COMPLETED` | Os recursos permanecem debitados. A liquidação está confirmada. |
| `FAILED` | Os recursos reservados são **liberados** de volta ao saldo disponível. Não houve débito. |
| `DECLINED` | Os recursos reservados são **liberados** de volta ao saldo disponível. Não houve débito. |
| `RETURNED` | Os recursos debitados são **creditados de volta** ao saldo disponível. A Ripple trata a devolução automaticamente. |


## Acompanhamento das mudanças de estado com webhooks

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**

```json
{
  "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"
}
```

Entrega fora de ordem
A ordem de entrega dos webhooks não é garantida. As notificações podem chegar fora de sequência se houver novas tentativas. Use sempre os timestamps de `updatedAt` do endpoint de transições de estado para determinar a sequência de estados autoritativa.

Observação
As notificações de webhook de eventos `PAYMENT_STATE_TRANSITION` não incluem detalhes de erro, como códigos de motivo. Para obter os detalhes de erro de pagamentos `FAILED`, `DECLINED` ou `RETURNED`, chame `GET /v3/payments/{paymentId}` e inspecione o array `errors[]`.

## Como projetar um handler de estados robusto

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.


## Operações relevantes da API

| Operação | Método | Caminho |
|  --- | --- | --- |
| Criar um pagamento | POST | `/v3/payments` |
| Obter um pagamento por ID | GET | `/v3/payments/{paymentId}` |
| Obter as transições de estado pelo ID do pagamento | GET | `/v3/payments/{paymentId}/states` |
| Buscar pagamentos | POST | `/v3/payments/filter` |