# Payment lifecycle

This page outlines the lifecycle of a payment in Ripple Payments Direct, provides more details about each payment state, and explains how to find the current state of a payment.

A payment typically moves through the following phases in Ripple Payments Direct:

1. **Initiated**: The payment process begins when you submit a payment request that references an accepted quote. Ripple Payments Direct creates a payment in the `INITIATED` state.
2. **Validating**: The payment state changes to `VALIDATING` while the platform runs internal checks, such as validating payment details, checking limits, and reserving funds from your available balance.
  - If these checks succeed, the payment continues to `TRANSFERRING`.
  - If any issue prevents the payment from proceeding (for example, invalid or missing data, account status, compliance rules, or a platform error), the payment moves to the terminal `FAILED` state.
3. **Transferring**: As the payment moves through the network to the beneficiary, the payment state becomes `TRANSFERRING`. The payment amount is debited from your available balance, and Ripple or a downstream partner works to complete the payment.
  - If any issue prevents completion (for example, the destination bank rejects the payment, or a platform or network error occurs), the payment moves to the terminal `FAILED` state.
4. **Completed**: If the payment does not enter `FAILED` during the earlier phases, and the payout network successfully credits the beneficiary, the payment reaches the terminal `COMPLETED` state. In most cases, this means the beneficiary has received the funds.
5. **Returned**: In some cases, a payment that previously reached `COMPLETED` may later be sent back by a downstream institution or the beneficiary’s bank. When this happens, the payment moves to the terminal `RETURNED` state and the funds are returned to the originator. Returns are managed by Ripple and payout partners; customers cannot directly trigger returns.


The diagram below shows a simplified view of how a payment can move between states:

![Payment states](/assets/payment-states-rpd2.493bce414aede6caafbe17b40885e69c9de9b632bf27aefa9a252ea8f4943486.9aafb945.svg)

The [Payment states](#payment-states) section on this page provides reference descriptions for each state. For more details about how returns work and how to reconcile them, see [Payment returns](/products/payments-direct-2/v2025.11/api-docs/concepts/payment-returns).

## Payment states

The `paymentState` field of the payment object indicates the current state of a payment. This section describes each possible value and what it means for your payment.

Ripple Payments Direct 2.0 supports the following payment states:

| State   | Description |
|  --- | --- |
| `QUOTED` | A quote has been created, but you haven’t accepted it yet. The quote describes the proposed exchange rate, fees, and amounts for a potential payment. When you accept the quote and create a payment, the payment’s first state transition is from `QUOTED` to `INITIATED`. |
| `INITIATED` | You, the payment originator, have initiated a payment by submitting a payment request that references an accepted quote. Ripple Payments Direct creates a payment record with a unique identifier and sets `paymentState` to `INITIATED`. |
| `VALIDATING` | Ripple validates the payment details and reserves funds from your available balance. The platform performs checks such as data validation, limits, account status, and compliance rules. If these checks succeed, the payment moves to `TRANSFERRING`. If any issue prevents the payment from proceeding, the payment moves to the terminal `FAILED` state. |
| `TRANSFERRING` | The payment is moving through the network to the ultimate beneficiary. Funds have been reserved or debited from your available balance while Ripple and payout partners attempt to complete the payment. If any issue prevents completion, the payment moves to the terminal `FAILED` state. |
| `COMPLETED` | The payment has been successfully processed, and the beneficiary has been credited according to the agreed quote. This is a terminal state for payments that finish successfully. |
| `FAILED` | The payment could not be completed. Causes include invalid or missing data, account or limit issues, compliance rules enforced by Ripple or a downstream partner, or unexpected platform and network errors. The failure reason, if available, is returned in the error details. Reserved funds are released and returned to the originator’s available balance where applicable. |
| `RETURNED` | The payment was previously marked as `COMPLETED` but was later returned by a downstream institution (for example, the beneficiary’s bank) after the beneficiary was initially credited. This is a terminal state. The funds are returned to the originator, and the return is visible in your payment reports and notifications. Customers cannot directly trigger returns. |


## How to check the payment state

You can check a payment's current state and its state transitions either in the Ripple Payments UI or by using the Ripple Payments Direct 2.0 API.

### In the Ripple Payments UI

In the Ripple Payments web UI, open the payment details for the payment you want to inspect.

- The **Payment Details** tab shows the payment’s transition through states on a timeline. Each entry shows the state and the timestamp when the payment reached that state.
- The **Payment Object JSON** tab includes the full payment object. The `paymentState` field shows the current state of the payment.


### Using the Ripple Payments Direct 2.0 API

You can also check the payment state using the Payments API:

- To check the current state of a specific payment, call the `GET /payments/{paymentId}` endpoint. The response body includes the `paymentState` field.
- To check a payment’s state transition history, call the `GET /payments/{paymentId}/state-transitions` endpoint. The response shows each state, when the payment reached it, and the order of transitions over time.