Payment lifecycle

This page outlines the lifecycle of a payment in 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 Payments Direct:

1. Initiated: The payment process begins when you submit a payment request that references an accepted quote. 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 a predictable, user-correctable issue is found (for example, invalid or missing data, account status, or compliance rules), the payment moves to the terminal DECLINED state.
   • If an unexpected platform or system issue prevents processing, 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 a predictable, user-correctable issue is discovered at this stage (for example, the destination bank rejects the payment due to compliance rules or account status), the payment moves to the terminal DECLINED state.
   • If an unexpected platform or system error occurs, the payment moves to the terminal FAILED state.

4. Completed: If the payment does not enter DECLINED or 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:

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

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, including the new DECLINED state.

Payments Direct supports the following payment states:

• DECLINED: The platform or a downstream partner has refused to process the payment because the request is invalid or cannot be accepted in its current form. The issue is usually user-correctable (for example, fixing data, limits, or account status) and the payment is not retried automatically.
• FAILED: An unexpected platform or system error prevents the payment from being processed. These errors are not primarily about the validity of the payment instruction itself.
• RETURNED: The payment was completed and the beneficiary was initially credited, but the funds were later sent back, resulting in a terminal RETURNED state.

The state of a payment determines what has happened to the originator's funds:

For some payments, Payments Direct returns additional execution metadata in an optional payoutExecutionDetails field on the payment object. When present, this object includes the payment rail used, timing information, and network-specific tracking references such as transaction IDs and confirmation numbers.

The field is not returned on every payment. Do not build required workflows that depend on its presence. For more information, see Payout execution details.

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

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.

To check the current state of a specific payment, call GET /v3/payments/{paymentId}. The response body includes the paymentState field.

To retrieve the full history of state changes for a payment, call:

GET /v3/payments/{paymentId}/state-transitions

Each record in the response includes:

• updatedFrom: the state before the transition
• updatedTo: the state after the transition
• updatedAt: the timestamp of the transition

Example response (excerpt)

[
  {
    "updatedFrom": "INITIATED",
    "updatedTo": "VALIDATING",
    "updatedAt": "2026-03-01T14:22:10.123Z"
  },
  {
    "updatedFrom": "VALIDATING",
    "updatedTo": "TRANSFERRING",
    "updatedAt": "2026-03-01T14:22:18.456Z"
  },
  {
    "updatedFrom": "TRANSFERRING",
    "updatedTo": "COMPLETED",
    "updatedAt": "2026-03-01T14:22:45.789Z"
  }
]

Payments Direct sends a PAYMENT_STATE_TRANSITION webhook notification each time a payment changes state. This is the recommended approach for monitoring payment progress in production integrations, as it eliminates the need to poll.

The webhook payload includes the paymentId, the new paymentState, and additional context fields such as sourceCurrency, sourceAmount, destinationCurrency, payoutAmount, and beneficiaryToken.

Example webhook payload

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

For setup and configuration details, see Notification webhooks.

When building integration logic that reacts to payment states, follow these guidelines:

• Treat all terminal states explicitly. Handle COMPLETED, FAILED, DECLINED, and RETURNED as distinct outcomes with different downstream behavior.
• For JIT-funded payments, monitor AWAITING_FUNDING. If your integration uses JIT_FUNDING, track this state and ensure funds are transferred before jitFundingExpiresAt. A payment that expires in AWAITING_FUNDING requires a new quote and payment.
• Do not assume state order from webhooks. Use GET /v3/payments/{paymentId}/state-transitions to confirm the authoritative sequence if delivery order matters.
• For FAILED and DECLINED, fetch the full payment object to retrieve error details before deciding whether to retry. Webhook payloads include the new paymentState but not the error code.
• Implement idempotency on state handlers. Webhooks may be delivered more than once. Your handler should be safe to call repeatedly for the same paymentId and paymentState.
• Handle unknown states gracefully. Log and alert on unexpected state values, but do not discard the event.