Using On-Demand Liquidity

Institutions integrate with the RippleNet API to send payments through On-Demand Liquidity, which delivers outbound payments through local rails, such as SPEI.

This document and the following diagram describe how funds flow between RippleNet customers and counterparties using On-Demand Liquidity, including the outbound transfer from the counterparty.

See the following diagram for an illustration of the flow, and the following sections for detailed descriptions of those processes.

RippleNet to On-Demand Liquidity Payment Flow

Account funding flow

Before you use RippleNet with On-Demand Liquidity, you must fund your accounts at the digital asset exchanges.

Funding an account requires these steps, which occur out-of-band:

  1. Prior to the Sending Institution initiating payments through On-Demand Liquidity, Ripple will fund the Sending Institution’s XRP wallet with a predetermined amount of XRP.
  2. In order for Ripple to prefund the XRP, the Sending Institution must onboard with a Ripple entity and enter into a Commit to Sell Agreement to permit them to hold XRP owned by Ripple.

Ripple Customer and Partner Engineers then peer your institution's accounts to your digital asset exchange (DAE) accounts, creating liquidity relationships for On-Demand Liquidity. After liquidity relationships are created and you have created an API key and secret uploaded to Ripple Payments (see Connecting to digital asset exchanges for more information), your institution can use RippleNet to view the balances of your accounts at your RippleNet counterparties for all currencies. For more information, see Get Balances in the RippleNet API Reference. You can also use Get Statement to view transactions for account reconciliation using specific account addresses.

Payment flow

RippleNet sends payment instructions to the On-Demand Liquidity service across RippleNet. The preceding image shows the request and response for each API operation. There are three main phases in the payment process:

Quoting

Two-way messaging allows parties to agree to terms for a payment before executing it.

The quoting phase involves the following steps:

  1. Get Quotes

    a. Your institution's integration logic makes a Create Quote Collection request to RippleNet.

    b. RippleNet forwards this request to On-Demand Liquidity, which retrieves and returns the FX rate, factoring in all negotiated incentives and fees.

    c. On-Demand Liquidity returns the rate and other payment information to RippleNet.

    d. RippleNet returns the quotes to your institution's systems, where you can review them. Note: Quotes for payments using On-Demand Liquidity expire in 70 minutes. Allow enough time for payment settlement when accepting a quote.

  2. Accept Quote

    a. You review the available quotes and select the one that best fits your needs. Then your integration logic makes a request to the RippleNet Accept Quote method. Accepting the quote means you accept the terms of the payment defined in the quote. Your institution includes any required compliance information for both the originator and beneficiary in this request.

    b. RippleNet forwards this request to On-Demand Liquidity.

    c. On-Demand Liquidity generates a payment ID, locks the quote, and returns the payment object to RippleNet in a LOCKED state.

    d. RippleNet updates the payment to the LOCKED state and returns it to your institution's systems.

Settlement execution

Once the terms of the payment are agreed upon, a payment is in a LOCKED state and execution can begin.

Settlement execution follows these steps:

  1. Your institution's integration logic makes a Settle Payment request to RippleNet to send instructions that start execution of the payment.
  2. RippleNet forwards this request to On-Demand Liquidity. On-Demand Liquidity begins the payment's execution process and updates the payment state to EXECUTING .
  3. On-Demand Liquidity updates the payment and returns the updated payment to RippleNet.
  4. RippleNet receives the response and updates the state of the payment in its database. RippleNet returns the response to your institution's internal systems.

Status confirmation

To check the status of any payment, make a Get Payments request.

Account reconciliation

You can check exchange account transaction balances and reconcile RippleNet payments using the RippleNet Get Account Statement API operation.

The response from the RippleNet Get Account Statement API operation includes the following information for On-Demand Liquidity account activity:

  • Historical exchange account activity up to 90 days.
  • For any activity related to a RippleNet payment, the RippleNet payment_id is specified by the transaction_id field.
    • The venue_id field represents an order trade or transfer transaction made by a digital asset exchange, and holds the value of the exchange-generated id for that transaction.
  • The balance_result field includes only RippleNet-related transactions.
    • Any "off-RippleNet activity", such as exchange account funding or withdrawal, has a transaction_id set to 00000000-0000-0000-0000-000000000000 .
Note

You must be using RippleNet v4.7.0 or higher to use the Account Reconciliation feature. The venue_id field requires RippleNet Server 4.10 or higher.

To get a statement for an exchange account using On-Demand Liquidity, make the following request:

GET {ripplenet_base_url}/v4/statement/{account_name_with_address}

For {account_name_with_address}, use the RippleNet account name and address for which you want to return a statement. Use the format accountname@ripplenetaddress.

For example, bitstamp_usd@rn.xrapid.mycorp or bitstamp_xrp@rn.xrapid.mycorp.

The Get Account Statement API operation requires the query parameters described in the following table:

Field Type Description
start-date Date The lower bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC. For example, 2020-03-18T20:30:00Z.
end-date Date The upper bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC For example, 2020-03-18T22:45:00Z.

You can provide optional page and size query parameters to paginate and limit the amount of transactions returned in the response. For more information, refer to the GET Account Statement API operation in the RippleNet API Reference.

Get Account Statement: HTTP request

Copy
Copied!
GET v4/statement/bitstamp_usd@rn.xrapid.mycorp?start-date=2020-03-18T20:30:00Z&end-date=2020-03-18T22:45:00Z HTTP/1.1
Host: https://sf-bank.ripplenet.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsieGN1cnJlbnQiXSwic2NvcGUiO

Get Account Statement: cURL request

Copy
Copied!
curl -X GET  \
https://https://sf-bank.ripplenet.com/v4/statement/bitstamp_usd@rn.xrapid.mycorp?start-date=2020-03-18T20:30:00Z&end-date=2020-03-18T22:45:00Z  \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsieGN1cnJlbnQiXSwic2NvcGUiO'  \
-H 'Content-Type: application/json'

Response (success)

Copy
Copied!
{
	"account_name": "bitstamp_usd",
	"start_datetime": "2020-03-18T20:30:00Z",
	"end_datetime": "2020-03-18T22:45:00Z",
			"generated_at": "2020-03-19T21:03:35.039Z",
			"currency": "USD",
			"owner": "rn.xrapid.mycorp",
			"opening_balance": "555.47000000",
			"closing_balance": "288.37000000",
			"transactions": {
				"content": [
					{
						"transaction_id": "b3758cf0-9706-44b2-9202-9fcf1fe652a3",
						"transaction_type": "PAYMENT",
						"transaction_state": "COMPLETED",
						"balance_change": "25.00599757",
						"balance_result": "504.37000000",
						"created_at": "2020-03-18T20:37:01.567Z",
						"end_to_end_id": null,
						"internal_id": "68eec670-8a9d-4b95-b0b2-e072b93e2250",
								"venue_id": "22frd599-4g9o-5b42-f0g5-y052b93e2211",
						"returns_payment_with_id": null,
						"returned_by_payment_with_id": null
					},
					{
						"transaction_id": "eea7e05f-5f8a-4040-bb18-3fdfdb46919c",
						"transaction_type": "PAYMENT",
						"transaction_state": "COMPLETED",
						"balance_change": "-25.27000000",
						"balance_result": "479.36000000",
						"created_at": "2020-03-18T20:36:52.86Z",
						"end_to_end_id": null,
						"internal_id": "57f31f30-b2e2-479e-8c07-4326f537bb08",
								"venue_id": "35ref699-5r4g-5a96-c0b1-h272b63f2299",
						"returns_payment_with_id": null,
						"returned_by_payment_with_id": null
					},
					{
						"transaction_id": "cde4a991-66df-4019-81b9-f1bc94dcb392",
						"transaction_type": "PAYMENT",
						"transaction_state": "COMPLETED",
						"balance_change": "-25.20000000",
						"balance_result": "504.70000000",
						"created_at": "2020-03-18T20:34:52.847Z",
						"end_to_end_id": null,
						"internal_id": "b2c33a25-69dd-466a-b771-d701401e0418",
								"venue_id": "1a9d-68eec670-h0b2-3f95-e072b93e2231",
						"returns_payment_with_id": null,
						"returned_by_payment_with_id": null
					}
						...
						...
					],
					"total_elements": "103",
					"sort": null,
					"first": false,
					"last": true,
					"number": "1",
					"numberOfElements": "4",
					"size": "100",
					"totalPages": "2"
				}
				}