{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/introduction/concepts/payment-lifecycle/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Payment lifecycle and payment states

\n

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.

\n

A payment moves through the following states in Ripple Payments Direct:

\n
    \n
  1. \nInitiated\n: The payment process begins when you submit a payment request by accepting the quote for the payment.\n\n \nRipple Payments Direct\n creates a payment in the \nINITIATED\n state.\n
    2. \n
  2. \nValidating\n: The payment state changes to \nVALIDATING\n while Ripple performs certain checks. \n\n
    \n\n\nIf any of the checks fail, the payment reaches the terminal \nFAILED\n state.\n\n
    3. \n
  3. \nTransferring\n: As the payment moves through the network to reach the beneficiary, the payment's state changes to \nTRANSFERRING\n while Ripple performs additional checks. \n
    \n If any of the additional checks fail, the payment reaches the terminal \nFAILED\n state.\n
    4. \n
  4. \nCompleted\n: If the payment didn't fail during one of the previous state transitions, the payment succeeds and transitions to the terminal \nCOMPLETED\n state.\n
    5. \n
\n

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

\n

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.

\n

\"Payment

\n

Payment states

\n

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.

\n

Ripple Payments Direct supports the following payment states:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
State
Description
QUOTEDA 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.
INITIATEDYou, 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.
VALIDATINGRipple validates the payment details and reserves funds from your available balance to complete the payment.
TRANSFERRINGThe payment is moving through the network to the ultimate beneficiary. The payment amount is debited from your available balance.
COMPLETEDThe payment is complete and the beneficiary has received the funds.
FAILEDThe 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.
\n

How to check the payment state

\n

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.

\n

Check the payment state in the Ripple Payments UI

\n

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

\n

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.

\n

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

\n

Check the payment state using the Ripple Payments Direct API

\n

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.

\n

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.

","headings":[{"value":"Payment lifecycle and payment states","depth":1},{"value":"Payment states","depth":2},{"value":"How to check the payment state","depth":3},{"value":"Check the payment state in the Ripple Payments UI","depth":4},{"value":"Check the payment state using the Ripple Payments Direct API","depth":3}]},"contentItem":{"data":{"lastModified":"2025-11-13T00:24:58.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":false,"disableLastModified":true,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"8b134f11-967c-536c-95f7-c7fa84252027__redocly content/introduction/concepts/payment-lifecycle/","seo":{"title":"Payment lifecycle and payment states","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"introduction/concepts/payment-lifecycle.md","pageBaseUrl":"/introduction/concepts/payment-lifecycle","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Payment lifecycle and payment states","id":"payment-lifecycle-and-payment-states"},{"depth":2,"value":"Payment states","id":"payment-states"},{"depth":3,"value":"How to check the payment state","id":"how-to-check-the-payment-state"},{"depth":4,"value":"Check the payment state in the Ripple Payments UI","id":"check-the-payment-state-in-the-ripple-payments-ui"},{"depth":3,"value":"Check the payment state using the Ripple Payments Direct API","id":"check-the-payment-state-using-the-ripple-payments-direct-api"}]},"data":{"title":""},"catalogInfo":null,"link":"/introduction/concepts/payment-lifecycle/","sidebarName":"__root-sidebar__-data-69308394-sidebars.yaml","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}