{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/payments-odl/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Payment flow","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com/products/custody","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"payment-flow","__idx":0},"children":["Payment flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This concept article presents an overview of the main payment flow options when sending and receiving a payment using the RippleNet API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview--payment-flows-and-the-orchestration-api-operations","__idx":1},"children":["Overview — payment flows and the Orchestration API operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you are a developer of a new client application, you should use ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["orchestration"]}," to send or receive payments. These API operations automatically take care of many of the steps in a transaction, including the steps that most client applications don’t need to perform on a regular basis."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Note about the terms '_orchestration_' and '_templates_'"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The term ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["orchestration"]}," refers to a pre-defined sequence of actions that occur during the payment flow. The sequence is governed by an ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["orchestration template"]}," (sometimes referred to as a ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["workflow template"]},") that defines the action that the RippleNet service takes automatically at each stage of the payment process."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Orchestration templates are pre-defined by Ripple."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two main advantages to using the orchestration API operations:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The orchestration operations simplify the process of completing a payment, particularly for the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]},", as the orchestration operations can execute multiple steps automatically, such as accepting quotes and initiating the final settlement as soon as the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," locks the payment."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," can take advantage of ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["webhook"]}," notifications that are supported by the orchestration operations, rather than requiring their client applications to poll RippleNet repeatedly for changes in the payment state. For more information, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/best-practices/webhooks"},"children":["Webhooks"]},"."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"terminology-review-originator-sender-receiver-beneficiary","__idx":2},"children":["Terminology review: originator, sender, receiver, beneficiary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you read this overview of RippleNet payment flows, make sure you're familiar with the terms we use to describe the participants in any payment transaction, specifically the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["originator"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]},", and the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are explained in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/concepts/payment-participants"},"children":["Payment participants"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-flow-options","__idx":3},"children":["Payment flow options"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two options for the payment flow between the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The simplest payment flow automates the quote acceptance step for the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A second variation lets the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," manually accept the quote before the transaction completes."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These payment flow options are described below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-flow-with-automatic-quote-acceptance","__idx":4},"children":["Payment flow with automatic quote acceptance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The default payment flow is the simplest workflow for both the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]},". The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," executes a single action to create the payment, and steps for requesting, accepting, and locking a quote occur automatically."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/basic-payment-flow-1.f5c426c3b2d2ccc5f20780758c5df758da1986f494fde6f993a46256c704219a.ac9c5631.svg","alt":"Payment flow with automatic quote acceptance"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These steps are as follows:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Originator requests a payment."]}," The first step of a payment transaction happens outside of the RippleNet pipeline, when the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["originator"]}," contacts the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," to begin a payment transaction."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sender creates payment."]}," The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," creates an ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["orchestration payment"]},", a payment that follows a pre-approved workflow template to request, receive, and accept a quote, and to prepare the quote for settlement when the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," locks the quote. This initiates the payment with a status of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPTED"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Receiver locks the payment."]}," The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," executes their required validation checks—including information validation and regulatory compliance checks—in accordance with their internal policies, and locks the payment. At this point, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," can query the payment and verify that its state is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCKED"]},", but doesn't have to do anything further, as RippleNet automatically submits the payment for settlement, and the payment state changes to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXECUTED"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Receiver delivers funds to the beneficiary."]}," After the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," has received the notification of successful settlement of the payment on the RippleNet Server, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," either credits the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]}," account or forwards the payment to the local clearing system, as applicable."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Receiver marks the payment as completed."]}," After receiving the confirmation that the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]}," has received the funds or the payment has been forwarded to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]},"'s institution, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," updates the payment status to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},"."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-flow-with-manual-quote-acceptance","__idx":5},"children":["Payment flow with manual quote acceptance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A variation of the default payment flow gives the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," more control over the steps of fetching and accepting a payment quote. For the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]},", there is no difference."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/basic-payment-flow-2.df3cb536931d884535f7d0246f632d9475dbc9171d8b20050c5b573c5a0a0454.ac9c5631.svg","alt":"Payment flow with manual quote acceptance"},"children":[]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Originator requests a payment."]}," The first step of a payment transaction happens outside of the RippleNet pipeline, when the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["originator"]}," contacts the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," to begin a payment transaction."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sender requests a quote."]}," The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," asks all participants and liquidity providers for a quote of the planned payment."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sender accepts the quote."]}," The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," can either accept or reject the quote. The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," must do this before the quote expiry date/time. Accepting the quote initiates the payment with a status of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPTED"]},", and the sender must include the identifying information of the originator and beneficiary of the payment at this step."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Receiver locks the payment."]}," The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," executes their required validation checks—including information validation and regulatory compliance checks—in accordance with their internal policies, and locks the payment. At this point, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sender"]}," can query the payment and verify that its state is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCKED"]},", but doesn't have to do anything further, as RippleNet automatically submits the payment for settlement, and the payment state changes to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXECUTED"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Receiver delivers funds to the beneficiary."]}," After the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," has received the notification of successful settlement of the payment on the RippleNet Server, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," either credits the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]}," account or forwards the payment to the local clearing system, as applicable."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Receiver marks the payment as completed."]}," After receiving the confirmation that the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]}," has received the funds or the payment has been forwarded to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]},"'s institution, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiver"]}," updates the payment status to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},"."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more about payment states, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/concepts/payment-states"},"children":["Payment states"]}," concepts page."]}]},"headings":[{"value":"Payment flow","id":"payment-flow","depth":1},{"value":"Overview — payment flows and the Orchestration API operations","id":"overview--payment-flows-and-the-orchestration-api-operations","depth":2},{"value":"Terminology review: originator, sender, receiver, beneficiary","id":"terminology-review-originator-sender-receiver-beneficiary","depth":2},{"value":"Payment flow options","id":"payment-flow-options","depth":2},{"value":"Payment flow with automatic quote acceptance","id":"payment-flow-with-automatic-quote-acceptance","depth":3},{"value":"Payment flow with manual quote acceptance","id":"payment-flow-with-manual-quote-acceptance","depth":3}],"frontmatter":{"seo":{"title":"Payment flow"}},"lastModified":"2025-10-16T01:30:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-odl/introduction/concepts/payment-flow","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}