RippleNet Home payments reference
The Payments page and its associated pages in RippleNet Home displays a RippleNet instance’s payments and payment details. Details include status, history, and parameters. The Payments pages can also, if enabled, initiate new payments.
This reference page explains important payment concepts and describes the Payments page set features in detail. For a high-level overview of RippleNet Home and other basic concepts, see the RippleNet Home Overview.
Payment concepts
This page provides a high-level view of payment concepts that apply to RippleNet Home. For more details on any of these concepts, and a bit more background on how payments work in RippleNet, go to Concepts.
Payment parties
It's important to understand the parties involved in a RippleNet payment. For a quick introduction to the terms originator, sender, receiver, and beneficiary, please see the concepts article, Payment participants.
A quick overview: In a full payment chain, an originator requests a payment to a beneficiary through the sender and receiver institutions. The sender institution uses the oringator's funds to send the payment to the receiver institution through a set of one or more intermediate instances. The receiver institution then pays the funds to the beneficiary.
Note
There are numerous variables in this chain of payment parties. A payment might have no originator or beneficiary, but is simply a payment between RippleNet institutions. The set of intermediate instances is determined by RippleNet, and can vary from payment quote to payment quote.
Payment quotes
Payment quotes allow the sender to review the terms of a payment before beginning the process to send a payment. Those terms can include foreign exchange rates (if the payment involves currency exchange) and fees. Any of the parties involved in the payment, including intermediate instances, can set these terms. It’s important that the sender and receiver know what terms affect the payment, and what amount will finally make it to the receiver and beneficiary after all fees and exchange rates are applied.
For a quick introduction to quotes, and their role in RippleNet payments, see the concept article Quotes.
Payment states
A payment, created when a sender accepts a payment quote and generates a payment request, goes through a series of significant stages. RippleNet assigns each of the significant stages a payment state that reports where in the payment process a payment currently stands.
A payment’s first state is Accepted, which reports that the sender has accepted a payment quote and a payment request is out for consideration by the receiver and intermediate instances. The payment then proceeds through a variety of states depending on how it’s handled, and can end in any number of states depending on success, failure, or other conditions at each stage.
A synopsis of possible RippleNet payment states:
- Accepted: The sender has accepted a payment quote.
- Locked: The receiver has agreed to proceed with the payment and has locked payment terms.
- Lock Declined: The receiver has rejected the payment request.
- Prepared: The sender has prepared funds for payment and has requested the other parties to settle the payment by transferring funds to the receiver. This is a transitory state enacted by RippleNet.
- Executed: Funds have been transferred from the sender’s account to the receiver’s account.
- Settlement Declined: At least one institution in the payment chain wasn’t able to fulfill the payment due to insufficient funds.
- Returned: The receiver accepted the payment funds, but has returned them to the sender by successfully completing a new return payment. Once a payment enters a Returned state, it has reached a final state and can enter no other states.
- Failed: Any one of the payment parties has actively stopped payment, or the payment has expired.
- Completed: The receiver has verified that payment has reached the intended beneficiary.
Payment states and the way a payment moves from state to state is an involved topic. For more detailed information, see Payment States.
RippleNet payment objects
Each payment within RippleNet is defined by a RippleNet payment object (RPO), a JSON structure that describes all of the current attributes of a payment. These attributes include sender, receiver, intermediate instances, amounts, current state, and many more. Many of these attributes are self-evident key:value pairs.
For more details about RippleNet Payment Objects, see SRPO overview.
Payment event trails
Each RippleNet instance (including yours) records any actions in RippleNet that involve payments handled at some point by the instance. The instance receives these actions—if they take place outside the instance—as messages from parties involved in the payment. Each message includes any change of the payment’s state.
A payment’s event trail is a JSON structure within an RPO that includes a key:value description of each message that involves the payment. Values provide date and time, sender, action taken, and more.
A payment event trail is a valuable tool for tracking down problems with a payment.
RippleNet Home’s Payments page set
RippleNet Home's Payments page set turns RPOs and event trails into human-readable information that provides a simpler view of an institution’s payment activities than a collection of JSON files. It also provides access to JSON file details if needed.
To access the Payments page set, click
(Payments) in the left nav bar.
Payments page
The Payments page provides a comprehensive list of payments sent or received by your institution. You can view all of your institution’s payments, or use the page’s Filters panel to narrow payments down to a meaningful subset.
Payment Details page
You can open a Payment Details page for any one of the payments presented in the Payments page. The page offers three tabs:
- The Payment Details tab provides a graphic view of parts of a payment’s event trail that include payment amounts and states.
- The Payment Object JSON tab presents the RPO that defines the payment.
- The Event Trail JSON tab presents the payment’s full event trail.
New Payment page
Some RippleNet instances are configured to allow creating new payments through RippleNet Home. A New Payment button appears on the Payments page if this feature is enabled. Click the button to open the New Payment page.
Get Quote display
The New Payment page initially displays fields that define a requested payment quote and submit the request for acceptance and consideration by other parties involved in the payment.
Accept quote display
After other parties have considered the payment request and respond with a quote of payment terms, the New Payment page displays quote terms and provides a place for the sender to provide additional information before accepting the quote.
Payments page
The Payments page provides a comprehensive list of your institution’s payments and filter controls that let you focus on the payments that interest you most.
Payment list
The payment list presents a table of payments, one per line, each payment defined by its own RPO (Ripple Payment Object). Payments here are any RippleNet payments in which your institution was the sender or receiver.
Payment list columns
The payment list columns each display a different aspect of a payment.
| Column | Description |
|---|---|
| Payment ID | The unique ID assigned to the payment when the payment was created. Note that this ID value is in random order, not sequential. The ID is a link that, when you click it, opens the Payment Details window for the payment’s RPO. |
| Source | The RippleNet instance of the sender. |
| Destination | The RippleNet instance of the receiver. |
| Amount | The type of currency and amount specified for payment. Note that the amount can be different at different stages of the payment (due to fees and other changes). The original payment request specifies whether this amount is at the point of the originator, sender, receiver, or beneficiary. |
| Last Modified | The date and time the payment’s RPO was last modified. |
| Status | The current progress and status of the payment, represented by a set of four progress bars followed by the payment state. The progress bars fill in with color from left to right to show the progress of the payment. The color of the progress bars show payment health:
|
| Settle | This column, untitled, appears only when a payment is initiated through RippleNet Home’s optional New Payment feature and that payment is awaiting your approval. Clicking the Settle button that appears in the payment entry opens the Payment Details page for the payment. You can settle the payment there so that the payment can go through. |
more options |
Offers a single menu item: View Details. Choosing this item opens the Payment Details window for the payment’s RPO. |
Payment list controls
The Payments page offers a set of payment list controls that help you manage your view of payments. Controls along the top of the page:
| Control | Action |
|---|---|
Environment |
Choose the environment in which payments are reported in the display list. |
New Payment |
Open the New Payment window. Only available if your instance is configured to make payments through RippleNet Home. |
Refresh |
Redisplay the payments list to show the most recent payments. |
Download |
Open the Download Payment dialog box where you can specify a single page of payments to download from the payments currently displayed in the payments list. Each downloaded page contains 100 payments in order from most recently modified to least recently modified payment. The download file is a comma-separated values (CSV) file. |
Filter |
Open the Filters panel where you can set filters to reduce the number of payments displayed (described below). Also displays the number of filters currently in effect. |
Controls on the bottom of the page specify display list pagination:
| Control | Action |
|---|---|
Rows per page |
Specify the number of payments to display in the current page of the payments list. |
Page number |
Choose the page number of the page to display in the payments list. |
Filters panel
On the Payment page, click Filter to open the Filters panel. The panel displays a set of filters that each specify a subset of payments to list. Filters combine to determine the payments displayed in the payment list: each payment in the list must match all specified filters. Once applied, the filters also determine what payments RippleNet Home downloads when using the Download button.
| Filter | Effect |
|---|---|
| Sender End-to-End ID | Displays only payments with the specified sender end-to-end ID. This ID is not a RippleNet value—it’s an arbitrary value set in a payment’s RPO by the sender or receiver, typically a value agreed upon by both parties, used for their own purposes. |
| Internal ID | This filter is not currently used and has no effect. |
| Payment ID | Displays only the payment with this unique payment ID. Because payment IDs are unique to each payment, using this filter specifies a single payment. |
| Payments Created After | Displays only payments created on or after the specified date. This value may be entered in MM/DD/YYYY format, or selected from the calendar dropdown in the box. The payment creation date is specified by the contract: {created at:} parameter in the payment’s RPO. |
| Sending Host | Displays only payments sent by the specified RippleNet address. |
| Sending Account | Displays only payments sent from the specified RippleNet account. |
| Receiving Host | Displays only payments received by the specified RippleNet address. |
| Receiving Account | Displays only payments received by the specified RippleNet account. |
| Currency | Displays only payments sent or received using the specified currency. Must be entered as a three-character standard country currency code. This filter must be used with the Currency/Amount Type filter to specify whether this filter determines sent currency or received currency. |
| Minimum Amount | Displays only payment amounts of this amount or greater. This filter must be used with the Currency/Amount Type filter to specify whether this is a sent amount or a received amount. |
| Maximum Amount | Displays only payment amounts of this amount or less. This filter must be used with the Currency/Amount Type filter to specify whether this is a sent amount or a received amount. |
| Currency/Amount Type | Specifies whether the Currency, Minimum Amount, and Maximum Amount filters are determined as a payment’s sent amount or received amount. Choose either Currency/Amount Received or Currency/Amount Sent from the filter field’s pulldown. This filter must be used with any one or combination of the Currency, Minimum Amount, and Maximum Amount filters. |
| Payment State | Displays only payments currently in the specified payment state. Choose from the filter field's pulldown:
These states are described earlier in the Concepts section. |
| Payment Type | Displays only payments of the specified type. Choose from the filter field’s pulldown:
|
Filter controls
The Filters panel has two buttons on the bottom of the panel that control filtering once filtering is specified:
- The Apply Filters button closes the Filters panel and refreshes the display list to show only payments that match currently set filters. The Filter button at the top of the display shows how many filters are currently applied to the display list.
- The Clear All button clears all filter parameters from the Filters panel so that no filtering is set. Note that clearing filter parameters has no effect until clicking Apply Filters .
Payment Details page
The Payment Details page provides information about a single payment that goes beyond what displays in the payments list. Open it from the Payments page either by clicking a payment’s payment ID in the payments list, or by choosing View Details from the payment’s more options (
) menu. The top of the page displays the payment ID and the environment in which the payment exists.
If your instance is set up to make new payments through RippleNet Home, a Settle payment button may appear at the top right of the page when you’ve accepted a quote that your receiving partner has locked. Click the button to signal your approval of payment settlement.
The three tabs described below each provide a different set of information.
Payment Details tab
The Payment Details tab presents important parts of the payment’s event trail in graphic form:
- The chain of events on the left shows each step in the flow of funds that has occurred in payment thus far.
- The chain of events on the right shows each payment state transition and the elapsed time between them. Changes in green show successful states, changes in red show stalled or failed states.
Payment Object JSON tab
The Payment Object JSON tab displays the full text of the JSON file that defines the payment’s RippleNet payment object (RPO).
Standard RippleNet Payment Object Overview provides more detailed information about RPOs.
Event Trail JSON tab
The Event Trail JSON tab displays the full text of the JSON file that defines the event trail associated with the payment.
For more information about the fields in the Event Trail Object, see the response schema in the Get event trail for payment reference page.
New Payment page
The New Payment page starts a new payment sent by your institution. It requests one or more quotes from intermediate instances and a partner institution that receives payment.
Open the page by clicking the New Payment button on the Payments page. The button and this feature don’t appear for all RippleNet instances. An institution must request the New Payment feature from their Ripple representative if they find it useful to make payments manually instead of through the RippleNet API.
The New Payment page offers a basic set of fields that define a simple payment quote request and advanced options for more involved requests.
Basic payment fields
The basic payment fields in the New Payments page define the payment amount and currency, the receiving institution, where in the payment chain the amount is specified, and the payout method used to pay the beneficiary. These fields are all required to submit a quote request:
| Field | Definition |
|---|---|
| Quote Type | The stage in the payment chain where the amount specified in the Amount field applies. Amounts in stages before and after the specified stage may differ after fees are applied. The pulldown offers these values:
|
| Amount | The amount of payment in the stage and in the currency specified by the Amount Type and Sending Currency Code fields. |
| Payment Currency | The type of currency used to define the payment amount set in the Amount field. The value must be a three-letter standard international currency code. |
| Receiver RippleNet Host | The RippleNet address of your receiving partner’s RippleNet instance. You can get this address from your receiving partner. |
Payment Method Setting fields
The Payment Method Setting fields define how to pay the beneficiary. The fields are required, but take non-specific values by default:
| Field | Definition |
|---|---|
| Payout Method | The payout method your receiving partner will use to pay the beneficiary. The pulldown offers these values:
|
| Outlet ID or Payout Method | Required when Payout Method is set to Specific Method. The payout method or outlet ID you’d like your receiving partner to use for beneficiary payout. This is an arbitrary string you enter and your partner will read. You can agree on appropriate method or ID strings with your partner. Note that this field only appears when Payout Method is set to Specific Method. |
| Payout Method Category | The category of your payout method. The pulldown offers these values:
|
Use Previous Quote Configuration
The top of the New Payment page lists the most recent payment you made and offers the opportunity to repeat the same quote request. This is a convenient feature for periodically repeated payments such as a daily payment to the same receiver.
Click Use Previous Quote Configuration to set all the quote fields, both basic and advanced, to the settings you used for your previous payment. You can then alter any field values you want before submitting the quote.
Advanced Options fields
Advanced Options fields are sets of optional fields that can define a quote request beyond basic payment parameters.
Account Settings fields
A basic payment quote request assumes using your institution's default RippleNet account (if you have more than one) and your receiver's default RippleNet account (if they have more than one). Set these field values to specify other accounts.
| Field | Definition |
|---|---|
| Sender RippleNet Account | The RippleNet account name of your institution's account used to send this payment. |
| Receiver RippleNet Account | The RippleNet account name of your receiving partner’s account used to receive this payment. You can get this account name from your receiving partner. |
| Sender Segregated Account | The RippleNet account name of a receiving partner account that belongs to you (a nostro account). This account is used to send the payment. |
Currency Filter field
The Currency Filter field works on returned quotes to display only quotes that use your specified currency.
| Field | Definition |
|---|---|
| Sender or Receiver Currency | Filter all returned quotes to show only quotes that use the type of currency specified in the basic “Payment Currency” field. The filter is applied to the party specified in the “Quote Type” field. |
Rate Setting fields
The Rate Setting fields specify an exchange rate for the payment. When Custom Rate is unchecked, no exchange rate is specified for the quote. Checking Custom Rate opens exchange rate definition fields that you must fill in to specify an exchange rate:
| Field | Definition |
|---|---|
| Custom Rate | The ratio of the base currency to the counter currency. For example, 1.03 for the ratio of the Euro to the U.S. dollar (EUR/USD). The Rate Type value determines which currency is the base currency and which is the counter currency. |
| Rate Type | Which currency is the base currency and which is the counter currency when specifying the Rate value. The pulldown offers two choices:
|
| Base Currency | The type of currency used as the base currency. The value must be a three-letter standard international currency code. |
| Counter Currency | The type of currency used as the counter currency. The value must be a three-letter standard international currency code. |
Fee Setting field
The Fee Setting field allows you to specify a fee charged for the payment.
| Field | Definition |
|---|---|
| Custom Fee | The fee that you’d like applied at the first stage of the payment’s progress through intermediate instances. The fee value is the amount of fee you want to apply using the currency defined for the sender institution. This value overrides sending fees configured in your institution’s instance. |
Route Setting field
The Route Setting features allow you to override cached payment paths and force RippleNet to search again for possible paths. You can, if you wish, filter out returned paths to show only paths that include specified intermediate instances.
Force path finding & liquidity path finding, when checked, disregards cached paths for this quote request so that RippleNet will find one or more new possible paths for payment.
| Field | Definition |
|---|---|
| Quote Route | Filter returned quotes to show only those that use at least one of the intermediary institutions listed here. Accepts a set of one or more RippleNet addresses separated by commas. |
Get Quote button
The Get Quote button submits the payment quote request defined by the fields in the New Payment page. RippleNet determines possible routes to reach the receiving partner either directly or through intermediate instances. RippleNet returns a set of one or more quotes that show available payment options that include applicable fees and exchange rates.
Note
RippleNet typically returns just a single quote. If a quote request is for ODL payment, the returned quote is for a simple single-instance payment route.
Returned quotes information
When RippleNet returns a quote for a requested payment, the New Payment page displays quote information. This will usually be a single quote, but in some circumstances will be two or more quotes.
Quote details
The top of the page displays details of the returned quote or, if there are multiple quotes, of the best returned quote:
- The top left of the quote displays the sent and received amounts in graphic form. It shows the total amount paid by the sender (you) and the total amount received by the beneficiary. It also shows fees and exchange rates between steps in the payment chain.
- The top right of the quote displays why this is the best quote returned.
- The bottom of the quote presents the expiration time for the quote. If you want to accept the quote, you must do so before the expiration time.
- See Details/Collapse Details toggles the amount and type of information shown above and between each step in the quote.
Multiple quotes
When you receive more than one quote, RippleNet Home displays the quote with the best conversion rate, and labels it Best Converted FX Rate. Click View All Quotes below it to see all returned quotes, each in its own tile. Click on any tile to select the quote.
Optional sender information
The bottom half of the page provides optional fields that you can fill in to send along with your quote acceptance to your payment partner.
| Field | Definition |
|---|---|
| Internal ID | An ID value whose definition is defined internally between you and your payment partner. This is not a RippleNet-assigned ID. |
| End-to-End ID | An ID value whose definition is defined internally between you and your payment partner. This is not a RippleNet-assigned ID. |
| Additional Payout Info | Any additional information that you and your payment partner find useful to exchange, provided as key:value pairs in JSON format. |
Accept quote and Back
Click Accept quote to accept the quote presented on the page or, if there are multiple quotes, the selected quote on the page. The Payments page opens and displays the accepted quote at the top of the payment list. When the receiving institution locks in the quote, the Settle button appears in the payment line where you can click it to continue the payment process.
Click Back to go back to your filled-in New Payment quote details page. This rejects all the quotes you received and lets you amend the quote request to try again if you wish.