Skip to content

RippleNet Server API (4.0.0)

The RippleNet Server API provides you the ability to develop custom applications to manage or interact with your RippleNet instance.

Check out the best practices and tutorials.

Authentication

All API operations require a bearer access token for your target environment.<br>Learn how to request the access token.

API environments

The RippleNet Server API creates a dynamic [domainPrefix] that consists of {tenant}.{environment}.

Note: This example uses aperture as the tenant. Your tenant ID is different.

EnvironmentDomaing PrefixDomainBase URL
Testaperture.testripplexcurrent.comhttps://aperture.test.ripplexcurrent.com
UATaperture.uatripplexcurrent.comhttps://aperture.uat.ripplexcurrent.com
Productionaperture.prodripplexcurrent.comhttps://aperture.prod.ripplexcurrent.com
Languages
Servers
Mock server

https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/

https://[domainPrefix].ripplexcurrent.com/v4/

Account configuration

Operations

Auditing

Operations

Balances and statements

Operations

Beneficiary confirmation

Operations

Diagnostics

Operations

Exchange transfers

Operations

Fees

Operations

Liquidation configuration

Operations

Non-orchestration payments

Operations

Notifications

Operations

ODL flags configuration

Operations

Orchestration payments

Operations

Payment expiration

Operations

Payout method

Operations

Platform accounts

Operations

Pool accounts

Operations

Quote expiration

Operations

Quotes

Operations

Rates

Operations

Request for payment

Operations

Sender segregated account configuration

Operations

Transfers

Operations

schema

Operations

activity

Operations

Orchestration Template

Operations

diagnostics

Operations

payment

Operations

Create Quote Collection

Request

Creates a collection of quotes for a proposed payment.

Security
Bearer
Bodyapplication/jsonrequired
sending_addressstringrequired

RippleNet account name and address of the sender.

Format: accountname@ripplenetaddress

Example: new_york@rn.us.ny.new_york

Example: "sf@rn.us.ca.san_francisco"
receiving_addressstringrequired

RippleNet account name and address of the receiver.

Format: accountname@ripplenetaddress

Example: new_york@rn.us.ny.new_york

Example: "sf_gbp@rn.us.ca.san_francisco"
amountstring>= 1required

Amount to be sent or received, depending on the quote_type.

Use this table to determine what amount to assign.

Example: "1"

Quote typeAmount
SENDER_AMOUNTAmount to be sent by the payment originator
SENDER_INSTITUTION_AMOUNTSet to SENDER_INSTITUTION_AMOUNT to calculate the quote based on the amount to be sent, plus any fees collected by the sending institution
RECEIVER_AMOUNTAmount to be received by the payment beneficiary
RECEIVER_INSTITUTION_AMOUNTSet to RECEIVER_INSTITUTION_AMOUNT to calculate the quote based on the amount to be received, minus any fees collected by the receiving institution
Example: "1"
currencystringrequired

Currency code of the amount to be sent or received, depending on the quote_type.

Use this table to determine what currency code to assign.

Example: USD

Quote typeCurrency code description
SENDER_AMOUNTSpecify the currency code for the sending currency, for example USD
SENDER_INSTITUTION_AMOUNTSpecify the currency code for the sending currency, for example USD
RECEIVER_AMOUNTSpecify the currency code for the receiving currency, for example USD
RECEIVER_INSTITUTION_AMOUNTSpecify the currency code for the receiving currency, for example USD
Example: "USD"
quote_typestringrequired

Specifies how to calculate the quote.

Example: SENDER_AMOUNT

Enum ValueDescription
SENDER_AMOUNT

Quote based on the amount the payment originator or originating institution wants to send

SENDER_INSTITUTION_AMOUNT

Quote based on the amount (to debit the originator) is amount plus any fees to be collected by the sending institution

RECEIVER_AMOUNT

Quote based on the amount the payment beneficiary or beneficiary institution should receive

RECEIVER_INSTITUTION_AMOUNT

The amount (to credit the beneficiary) is amount minus any fees to be collected by the receiving institution

Example: "SENDER_AMOUNT"
sender_or_receiver_currencystring

Currency code of the sender or receiver based on quote_type.

If provided, you can use this to filter the options for quotes.

Example: "USD"
custom_feenumber

Custom fee for the sending account.

Setting this field overrides all fees configured on the sender's RippleNet instance.

custom_rateobject

JSON request object to specify a custom exchange rate during quote collection generation.

ratenumberrequired

Exchange rate for a base and counter currency.

base_currencystringrequired

Base currency of the exchange rate.

counter_currencystringrequired

Counter currency of the exchange rate.

rate_typestringrequired

Order type for the exchange rate. Valid values are sell or buy. <p><ul><li>When rate_type = buy, base_currency is source ccy and counter_currency is destination ccy.</li> <li>When rate_type = sell, base_currency is destination ccy and counter_currency is source ccy.</li> </ul></p>

Enum"buy""sell"
quote_routeArray of strings

Custom route that quote must follow.

Provide an array of RippleNet address strings that convey the route the quote must follow.

Example: g.us.ca.san_francisco

Example: ["rn.us.ca.san_francisco","rn.us.tx.austin","rn.us.ny.new_york"]
payment_methodstring

Payout method for the quote.

Senders can use this field to define the payout method that the receiver should use to deliver the payment to end customer.

On-Demand Liquidity (ODL) receivers should set payment_method to the outlet_id or the string none (not an empty value) to keep funds at the destination exchange when paying out to a local rail.

Caution: The existing quote parameter is named payment_method while elsewhere it is payout_method.

enable_quote_per_payout_methodboolean

Enable this flag to generate quotes using payout methods configured by the receiver.

Example: true
digital_asset_originationboolean

When true, this flag tells RippleNet to provide a full quote as if the payment originates in the specified source fiat currency.

The quote for the source exchange excludes trading fees.

On execution, the source exchange trade is skipped, and XRP is withdrawn from the source exchange as the first step.

Example: false
force_path_finding_and_liquidity_path_findingboolean

When true, this flag tells RippleNet to ignore cached value for path finding and liquidity path finding.

Force performing new path finding and liquidity path finding.

Default false
Example: false
payout_method_categorystring

Category the payout method will be associated with. Defaults to OTHER if not specified.

Enum ValueDescription
REAL_TIME_GROSS_SETTLEMENT_SYSTEM

Real-time gross settlement system

REAL_TIME_NET_SETTLEMENT_SYSTEM

Real-time net settlement system

MASS_NET_PAYMENT_SYSTEM

Mass net payment system

BOOK_TRANSFER

Book transfer

CASH_PAYOUT

Cash payout

WALLET_PAYMENT

Wallet payment

OTHER

Other

Example: "BOOK_TRANSFER"
sender_segregated_accountstring<= 254 characters

RippleNet account name and address of the sender owned account at receiver to be used for failure conversion (in case of payment failure).

Format: accountname@ripplenetaddress

Example: new_york@rn.us.ny.new_york

Example: "conct_php_receiver_coins_sender@receiver"
quote_limitinteger

Flag for truncating the total amount of quotes to a maximum amount after sorting and filters are applied. Optional.

quote_filter_typesArray of strings

Filter on a type of quote.

Items Enum ValueDescription
LIQUIDITY_WARNINGS

Filter for liquidity warnings

QUOTE_ERRORS

Filter for quote errors

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/v4/orchestration/payment/quote_collections \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sending_address": "sf@rn.us.ca.san_francisco",
    "receiving_address": "sf_gbp@rn.us.ca.san_francisco",
    "amount": "1",
    "currency": "USD",
    "quote_type": "SENDER_AMOUNT",
    "sender_or_receiver_currency": "USD",
    "custom_fee": 0,
    "custom_rate": {
      "rate": 0,
      "base_currency": "string",
      "counter_currency": "string",
      "rate_type": "buy"
    },
    "quote_route": [
      "rn.us.ca.san_francisco",
      "rn.us.tx.austin",
      "rn.us.ny.new_york"
    ],
    "payment_method": "string",
    "enable_quote_per_payout_method": true,
    "digital_asset_origination": false,
    "force_path_finding_and_liquidity_path_finding": false,
    "payout_method_category": "BOOK_TRANSFER",
    "sender_segregated_account": "conct_php_receiver_coins_sender@receiver",
    "quote_limit": 0,
    "quote_filter_types": [
      "LIQUIDITY_WARNINGS"
    ]
  }'

Responses

Successfully returned quote collection.

Bodyapplication/json
quote_collection_idstring(uuid)required

Unique identifier of the quote collection.

Example: "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"
quotesArray of objectsrequired
quote_idstring(uuid)required

Unique identifier for the quote.

Example: "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"
created_atstring(date-time)required

Date and time at which the quote was created, as an ISO-8601 timestamp in UTC.

Example: "2018-04-06T20:33:35Z"
expires_atstring(date-time)required

Date and time after which the quote and its pricing expire, as an ISO-8601 timestamp in UTC. Defaults to 300s/300000ms.

Example: "2019-04-06T20:33:35Z"
typestringrequired

Indicates how the amount field should be treated for calculating quote values. Valid values are SENDER_AMOUNT, SENDER_INSTITUTION_AMOUNT, RECEIVER_INSTITUTION_AMOUNT, and RECEIVER_AMOUNT.

Enum"SENDER_AMOUNT""RECEIVER_AMOUNT""SENDER_INSTITUTION_AMOUNT""RECEIVER_INSTITUTION_AMOUNT"
price_guaranteestringrequired

Indicates whether a quote's pricing is INDICATIVE or FIRM. An INDICATIVE quote allows for price movements between quote issuance and payment execution, such that the quoted amount and delivered amount may differ. A FIRM quote ensures that the quoted and delivered payment amounts are equal. Defaults to FIRM.

sender_addressstringrequired

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "new_york@rn.us.ny.new_york"
receiver_addressstringrequired

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "new_york@rn.us.ny.new_york"
amountstringrequired

Amount to be sent or received, depending on the type value.

Example: "100"
currency_codestringrequired

Currency code for the amount value.

Example: "USD"
currency_code_filterstringrequired

Currency code that can be used to filter quotes at the opposite end of the quote request. For example, you can filter by this currency code to find the receiving currency for a quote with a SENDER_AMOUNT quote_type. If not sent in the request, this field value is set to null.

Example: "EUR"
service_typestringrequired

Returns null.

quote_elementsArray of objectsrequired

Transfer and exchange elements. A transfer element represents a movement of funds between two accounts. An exchange element represents the exchange of currencies between two accounts.

quote_element_idstring(uuid)required

Unique identifier for the quote element.

Example: "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"
quote_element_typestringrequired

Type of quote element. Valid values are EXCHANGE, TRANSFER, EXCHANGE_TRADE, and CRYPTO_TRANSFER. <p><ul> <li>TRANSFER represents the movement of funds between two accounts.</li> <li>EXCHANGE represents the exchange of currencies between two accounts.</li> <li>EXCHANGE_TRADE represents the exchange of fiat to digital currency on a digital exchange.</li> <li>CRYPTO_TRANSFER represents the movement of digital funds between two digital exchanges.</li> </ul></p>

Enum"TRANSFER""EXCHANGE""EXCHANGE_TRADE""CRYPTO_TRANSFER"
quote_element_orderstringrequired

Order of each quote element along the liquidity path. If a quote includes five quote elements, each one is enacted according to its quote_element_order number to make the proposed payment.

sender_addressstringrequired

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "new_york@rn.us.ny.new_york"
receiver_addressstringrequired

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "new_york@rn.us.ny.new_york"
sending_amountnumberrequired

Amount the sender is sending.

Example: 100
receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 97
sending_feenumberrequired

Fees the sender is charging. When quote_element_type is set to EXCHANGE, this field value is always set to 0.

Example: 2
receiving_feenumberrequired

Fees the receiver is charging. When quote_element_type is set to EXCHANGE, this field value is always set to 0.

Example: 1
sending_currency_codestring

Currency code of the sending amount. Included in quote elements with quote_element_type set to EXCHANGE.

Example: "USD"
receiving_currency_codestring

Currency code of the receiving amount. Included in quote elements with quote_element_type set to EXCHANGE.

Example: "INR"
fx_rateobject

The details of an FX Rate for a quote or payment.

ratenumberrequired

Exchange rate between a base and counter currency.

Example: 3.25
base_currency_codestringrequired

Currency code of the base currency.

Example: "USD"
counter_currency_codestringrequired

Currency code of the counter currency.

Example: "GBP"
typestringrequired

Order type of the exchange rate. Valid values are buy or sell.

Example: "buy"
transfer_currency_codestring

Currency code of the transfer. Included in quote elements with quote_element_type set to TRANSFER.

liquidity_warningstringrequired

Triggered when a quote causes an account to go below its minimum_allowed_balance. Otherwise, this field value is set to null.

payment_methodstring

Payment method (payment outlet) to use for this quote.

quote_errorsArray of objects
failed_pathArray of objectsrequired

Quote path that failed.

sourcestringrequired

RippleNet account name and address of the source account, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

destinationstringrequired

RippleNet account name and address of the destination account, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

source_currencystringrequired

Currency associated with the source account.

destination_currencystringrequired

Currency associated with the destination account.

account_liquidity_relationship_idstring(uuid)

Unique identifier for an account liquidity relationship.

Example: "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"
peer_liquidity_relationship_idstring(uuid)

Unique identifier for a peer liquidity relationship.

Example: "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"
error_originstring

RippleNet address of where the error originated. For example, rn.us.ny.new_york.

error_messagestringrequired

Message that describes the error.

Response
application/json
{
  "quote_collection_id": "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6",
  "quotes": [
    { … }
  ],
  "quote_errors": [
    { … }
  ]
}

Get application info

Request

Gets application information.

Security
Bearer
curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/v4/orchestration/info \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully fetched application info.

Bodyapplication/json
namestring

Application name.

Example: "Integration Module"
versionstring

Application version.

Example: "1.2.0"
Response
application/json
{
  "name": "Integration Module",
  "version": "1.2.0"
}

tenant

Operations

Orchestration internal action

Operations

Orchestration internal payments

Operations

Orchestration internal notifications

Operations