Payment flow

This concept article presents an overview of the main payment flow options when sending and receiving a payment using the RippleNet API.

Overview — payment flows and the Orchestration API operations

If you are a developer of a new client application, you should use 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.

There are two main advantages to using the orchestration API operations:

1. The orchestration operations simplify the process of completing a payment, particularly for the sender , as the orchestration operations can execute multiple steps automatically, such as accepting quotes and initiating the final settlement as soon as the receiver locks the payment.
2. Both the sender and receiver can take advantage of 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 Webhooks .

Terminology review: originator, sender, receiver, beneficiary

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 originator, sender, receiver, and the beneficiary.

These are explained in Payment participants.

Payment flow options

There are two options for the payment flow between the sender and receiver.

• The simplest payment flow automates the quote acceptance step for the sender .
• A second variation lets the sender manually accept the quote before the transaction completes.

These payment flow options are described below.

Payment flow with automatic quote acceptance

The default payment flow is the simplest workflow for both the sender and receiver. The sender executes a single action to create the payment, and steps for requesting, accepting, and locking a quote occur automatically.

These steps are as follows:

1. Originator requests a payment. The first step of a payment transaction happens outside of the RippleNet pipeline, when the originator contacts the sender to begin a payment transaction.
2. Sender creates payment. The sender creates an 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 receiver locks the quote. This initiates the payment with a status of ACCEPTED .
3. Receiver locks the payment. The 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 sender can query the payment and verify that its state is LOCKED , but doesn't have to do anything further, as RippleNet automatically submits the payment for settlement, and the payment state changes to EXECUTED .
4. Receiver delivers funds to the beneficiary. After the receiver has received the notification of successful settlement of the payment on the RippleNet Server, the receiver either credits the beneficiary account or forwards the payment to the local clearing system, as applicable.
5. Receiver marks the payment as completed. After receiving the confirmation that the beneficiary has received the funds or the payment has been forwarded to the beneficiary 's institution, the receiver updates the payment status to COMPLETED .

Payment flow with manual quote acceptance

A variation of the default payment flow gives the sender more control over the steps of fetching and accepting a payment quote. For the receiver, there is no difference.

1. Originator requests a payment. The first step of a payment transaction happens outside of the RippleNet pipeline, when the originator contacts the sender to begin a payment transaction.
2. Sender requests a quote. The sender asks all participants and liquidity providers for a quote of the planned payment.
3. Sender accepts the quote. The sender can either accept or reject the quote. The sender must do this before the quote expiry date/time. Accepting the quote initiates the payment with a status of ACCEPTED , and the sender must include the identifying information of the originator and beneficiary of the payment at this step.
4. Receiver locks the payment. The 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 sender can query the payment and verify that its state is LOCKED , but doesn't have to do anything further, as RippleNet automatically submits the payment for settlement, and the payment state changes to EXECUTED .
5. Receiver delivers funds to the beneficiary. After the receiver has received the notification of successful settlement of the payment on the RippleNet Server, the receiver either credits the beneficiary account or forwards the payment to the local clearing system, as applicable.
6. Receiver marks the payment as completed. After receiving the confirmation that the beneficiary has received the funds or the payment has been forwarded to the beneficiary 's institution, the receiver updates the payment status to COMPLETED .

For more about payment states, see the Payment states concepts page.