Payment lifecycle and payment states

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 moves through the following states in Ripple Payments Direct:

  1. Initiated : The payment process begins when you submit a payment request by accepting the quote for the payment. Ripple Payments Direct verifies the validity of the originator and beneficiary identity information you provided and checks if the request contains all required details. Then, it creates a payment in the INITIATED state.
  2. Validating : The payment state changes to VALIDATING while Ripple performs additional checks, including verifying that your available balance is sufficient to complete the payment transaction.
    1. If your available balance is sufficient to fund the requested payment, the amount required to complete the payment is earmarked or "reserved" from your available balance. This amount is reserved to ensure that any subsequent payment requests don't impact the availability of funds to complete the in-progress payment.
    2. If your available balance is insufficient or any of the additional checks fail, the payment reaches the terminal FAILED state.
  3. Transferring : The payment's state changes to TRANSFERRING as it moves through the network to reach the beneficiary.
  4. Completed or Failed : The payment either succeeds and transitions to the terminal COMPLETED state, or it may fail and transition to the terminal FAILED state.

See the diagram below for a visual representation of how a payment moves through various states.

The Payment states section on this page provides more information about each state a payment moves through. For information about payment failures in particular, see Understanding and handling payment failures.

Payment states

Payment states

The PaymentState field of the payment object indicates the current state of a payment. A payment can only be in one state at any given time, so each subsequent state overrides previous states. This section lists the supported payment states and provides information on how to find a specific payment's current state and past states.

Ripple Payments Direct supports the following payment states:

State
 Description
QUOTED A quote has been created, but you haven't accepted it yet to initiate a payment.

Note: This state is not shown as part of the payment detail as the payment doesn't exist yet. If you use the Get state transitions by payment ID API call to get state transition information, the QUOTED state appears as the first payment state.
INITIATED You, the payment originator, have initiated a payment. The payment now has a unique paymentId that's the same as the quoteId of the quote you accepted.
VALIDATING Ripple validates the payment details and reserves funds from your available balance to complete the payment.
TRANSFERRING The payment is moving through the network to the ultimate beneficiary. The payment amount is debited from your available balance.
COMPLETED The payment is complete and the beneficiary has received the funds.
FAILED The payment failed. The failure reason, if available, is listed in the response. Funds that were previously reserved to complete the payment are released and added back to the available balance.

How to check the payment state

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

Check the payment state in the Ripple Payments UI

The Payment details page in the Ripple Payments UI provides information about a payment's state transitions and its current state.

The Payment Details tab shows the payment's transition through various states starting with the INITIATED state. The timestamp associated with each state specifies when the payment reached that state.

In the Payment Object JSON tab, the paymentState field shows the current state of the payment.

Check the payment state using the Ripple Payments Direct API

To check the current state of a specific payment, call the Get a payment by ID operation with the payment's unique paymentId in the request URL. The response body includes the paymentState field whose value indicates the payment's current state.

To check a payment's state transition history, call the GET state transitions by payment ID operation with the unique paymentId in the request URL. The response contains an array of objects that show the payment's transition between states and the time at which the state transition happened.