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. 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 request.
    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. Terminal state - 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.

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

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

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.