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. 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.

Environment	Domaing Prefix	Domain	Base URL
Test	`aperture.test`	`ripplexcurrent.com`	`https://aperture.test.ripplexcurrent.com`
UAT	`aperture.uat`	`ripplexcurrent.com`	`https://aperture.uat.ripplexcurrent.com`
Production	`aperture.prod`	`ripplexcurrent.com`	`https://aperture.prod.ripplexcurrent.com`

Servers

Mock server

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

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

Auditing

Use these operations to audit your accounts.

Operation	Method	Description
Get audits	GET	Gets an audit trail of user actions and configuration changes (to accounts, fees, and rates) on a RippleNet instance.
Get event trail for payment	GET	Gets an audit trail of a payment's state changes on a local RippleNet instance.

Operations

Balances and statements

Use these operations to view balances and statements for a ledger.

Operation	Method	Description
Get balances	GET	Get balances for local and remote accounts owned by a RippleNet address.
Get ledger balances	GET	Get balances for ledger owned by a RippleNet address.
Get statement	GET	Gets a statement for an account that lists payments and transfers that impacted the account's balance during a specified date-time range.
Get statement by external account ID	GET	Gets a statement for an account that lists payments and transfers that impacted the account's balance during a specified date-time range.
Get ledger account statement	GET	Get statement for a specified Ledger Account

Operations

Beneficiary confirmation

Use these operations to perform beneficiary confirmations.

Operation	Method	Description
Get account lookup by status	GET	Get Account Lookup entities by status and other filters.
Initiate account lookup	POST	Creates an Account Lookup request to validate a beneficiary's account details before sending a payment.
Complete account lookup	POST	Posts an Account Lookup response to validate a beneficiary's account details before payment.
Get account lookup by ID	GET	Gets an Account Lookup entity for its `account_lookup_id` value.

Operations

Diagnostics

Use these operations to view RippleNet Server health.

Operation	Method	Description
Check health	GET	Gets the health status of the xCurrent server.
Check heartbeat	GET	Gets the health status of the xCurrent server's peers.

Operations

Exchange transfers

Use these operations to manage exchange transfers.

Operation	Method	Description
Get exchange transfers	GET	List all exchange transfers.
Execute exchange transfer	POST	Execute an exchange transfer to move funds from one of your accounts in one currency, to another one of your accounts in another currency.
Get exchange transfer quote	POST	Requests a quote for an exchange transfer.
Complete exchange transfer	POST	Updates the status of an exchange transfer to `COMPLETED`. Make this request once the exchange transfer has been made on both the ledger and on internal systems.
Get exchange transfer by ID	GET	Gets an exchange transfer by ID.

Operations

Fees

Use these operations to configure fees.

Operation	Method	Description
Get fees	GET	List all fees.
Create fee	POST	Creates a fee.
Get fee by ID	GET	Gets a fee by ID.
Update fee	PUT	Updates an existing fee.
Delete fee	DELETE	Deletes a fee. Once deleted, a fee cannot be accessed.

Operations

Non-orchestration payments

Operations

Orchestration payments

Operations

Payment expiration

Use these operations to manage payment expirations.

Operation	Method	Description
Get payment expiry by ID	GET	Gets the time to live (ttl) of a payment expiry in seconds.
Update payment expiry	PUT	Updates the time to live (ttl) of a payment expiry in seconds.
Delete payment expiry	DELETE	Deletes a payment expiry.
Get payment expiries	GET	Returns all configured payment expiries.
Create payment expiry	POST	Creates a payment expiration window, or time to live (ttl), in seconds.

Operations

Payout method

Payout Method operations let receivers create and manage payout methods. Senders can generate quotes based on these receiver payout methods.

Operation	Method	Description
Create payout method	POST	Creates a payout method. For example, `LOCAL_RAILS`.
Get payout methods	GET	Returns a list of payout methods created by a receiving partner.
Get payout method by ID	GET	Returns a payout method by its ID.
Update payout method	PUT	Updates a payout method.
Delete payout method	DELETE	Deletes a payout method.
Get all categories	GET	Returns all the payout method categories.

Operations

Platform accounts

Use these operations to configure your RippleNet platform accounts.

Operation	Method	Description
Create platform	POST	Creates a RippleNet platform that represents a financial entity that holds accounts in the real world. For example, a Bank, Exchange, or Wallet provider.
Get all platforms	GET	Returns a list of all active RippleNet platforms.
Get platform by platform ID	GET	Get a RippleNet platform by its platform ID.
Update platform	PUT	Updates a RippleNet platform.
Delete platform by platform ID	DELETE	Deletes a RippleNet platform by its platform ID.
Create platform account	POST	Creates a RippleNet platform account, which represents a real-world account owned by a financial entity.
Get platform accounts	GET	Returns a paged list of all active RippleNet platform accounts.
Get platform account by platform account ID	GET	Gets a RippleNet platform account by its platform account ID.
Update platform account	PUT	Updates a RippleNet platform account.
Delete platform account by platform account ID	DELETE	Deletes a RippleNet platform account by its platform account ID.
Get platform accounts balances	GET	Get balances for local Platform Accounts
Get platform account statement	GET	Get statement for a specified Platform Account

Operations

Pool accounts

Use these operations to configure your RippleNet pool accounts.

Operation	Method	Description
Get all pool accounts	GET	Returns a list of all pool accounts on a RippleNet node.
Get pool account by pool account ID	GET	Get a pool account by its pool account ID.

Operations

Quote expiration

Use these operations to manage quote expirations.

Operation	Method	Description
List quote expiries	GET	Returns all configured quote expiries.
Create quote expiry	POST	Creates a quote expiration window, or time to live (ttl), in seconds.
Get quote expiry	GET	Gets the configured quote expiration window, or time to live (ttl), in seconds.
Update quote expiry	PUT	Sets a quote expiration window, or time to live (ttl), in seconds.

Operations

Quotes

Use these operations to manage your quotes.

Operation	Method	Description
Accept quote	POST	Accepts a quote ID to start the payment process.
Get quotes	GET	Gets a list of quotes.
Get quote by quote ID	GET	Gets a quote by ID.
Create quote collection	POST	Creates a collection of quotes for a proposed payment.
Get quote collection by ID	GET	Gets a quote collection that was created for a proposed payment.

Operations

Accept quote

Request

Accepts a quote ID to start the payment process.

Security

Bearer

Bodyapplication/jsonrequired

The JSON object to include in your request to accept a quote that you want to advance as a payment.

quote_idstring(uuid)required

ID of the quote to accept and continue as a payment.

Example: "9bb53b3b-a774-43e2-9a1b-f18fbc3640f7"

sender_end_to_end_idstring<= 128 characters

ID that the sender can specify. Persisted on all RippleNet instances that participate in the payment.

internal_idstring<= 128 characters

Internal ID that the sender can specify. Only visible to the sender. Only the sending RippleNet instance stores this ID.

user_infoobject

Your receiver defines the required User info structure. Provide the structure as required by your use case.

Payout Service (SLS) customers: Use the ISO20022 descriptions used with the RippleNet Payment Object (RPO) structure.

One-to-one liquidation customers: Use the Outbound instructions format.

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/payments/accept \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "quote_id": "9bb53b3b-a774-43e2-9a1b-f18fbc3640f7",
    "sender_end_to_end_id": "string",
    "internal_id": "string",
    "user_info": {}
  }'

Responses

Successfully accepted quote resulting in a payment object in ACCEPTED state.

Bodyapplication/json

payment_idstring(uuid)required

Unique identifier of a payment.

Example: "d485f100-2af7-4e48-9ab1-3c7e28775691"

contract_hashstringrequired

Hash of all values in the Contract object used to ensure immutability. Once a payment transitions to the LOCKED state, the values in this object cannot change.

Example: "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103"

payment_statestringrequired

State of the payment. For details about payment states, see Payment States in the RippleNet Developer Guide.

Enum"ACCEPTED""AWAITING_COLLECTION""COMPLETED""EXECUTED""FAILED""FORWARDED""LOCK_DECLINED""LOCKED""PREPARED""RETURNED"

Example: "COMPLETED"

modified_atstring(date-time)required

Date and time at which the payment was last modified, as an ISO-8601 timestamp in UTC.

Example: "2019-10-01T18:25:47.347Z"

contractobjectrequired

Represents all immutable parts of a payment agreed upon by all participants as a part of the Lock payment flow. Once a payment transitions to the LOCKED state, the values in this object cannot change.

sender_end_to_end_idstring[ 1 .. 128 ] charactersrequired

ID that the sender can specify. Persisted on all RippleNet instances that participate in the payment.

created_atstring(date-time)required

Date and time at which this payment contract was created, as an ISO-8601 timestamp in UTC.

Example: "2019-10-01T18:18:13.665Z"

expires_atstring(date-time)required

Date and time after which this payment contract expires, as an ISO-8601 timestamp in UTC.

Default "300s/300000ms"

Example: "2019-10-01T18:55:22.824Z"

quoteobjectrequired

JSON response object that represents a quote for a proposed payment or return payment.

quote_idstring(uuid)required

Unique identifier for the quote.

Example: "2a547e56-4aac-4375-86a8-8b3e7014801d"

created_atstring(date-time)required

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

Example: "2020-01-29T20:59:44.925Z"

expires_atstring(date-time)required

Date and time after which the quote and its pricing expire, as an ISO-8601 timestamp in UTC.

Default "300s/300000ms"

Example: "2020-01-29T21:29:44.925Z"

typestringrequired

Indicates how the amount field should be treated for calculating quote values.

Enum"SENDER_AMOUNT""RECEIVER_AMOUNT""SENDER_INSTITUTION_AMOUNT""RECEIVER_INSTITUTION_AMOUNT""REVERSAL_AMOUNT"

Example: "SENDER_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.

Default "FIRM"

Example: "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: "sf@rn.us.ca.san_francisco"

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: "sf_gbp@rn.us.ca.san_francisco"

amountstringrequired

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

Example: "1"

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: "259189e7-cb14-42e7-99ef-375f3285e356"

quote_element_typestringrequired

Type of quote element.<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>

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

Example: "EXCHANGE"

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.

Example: "1"

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: "sf@rn.us.ca.san_francisco"

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: "sf_gbp@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 1

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 355

sending_feenumberrequired

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

Example: 0

receiving_feenumberrequired

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

Example: 0

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: "GBP"

fx_rateobject

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

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

Payout method for the quote.

Example: "LOCAL_RAILS"

payment_method_fieldsstring

JSON object containing payment method metadata.

Example: "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}"

payout_method_infoobject

Details about the payout method.

payout_method_namestring

Payout method for the quote.

Example: "Cash Payout"

payout_method_categorystring

Category of the payout method. Defaults to <code>OTHER</code> if not specified.

Enum"REAL_TIME_GROSS_SETTLEMENT_SYSTEM""REAL_TIME_NET_SETTLEMENT_SYSTEM""MASS_NET_PAYMENT_SYSTEM""BOOK_TRANSFER""CASH_PAYOUT""WALLET_PAYMENT""OTHER"

Example: "BOOK_TRANSFER"

descriptionstring

User defined description of the payout method.

Example: "local rails"

estimated_time_to_creditstring

The estimated time to credit the beneficiary using this payout method.

Example: "3 days"

fee_infoobject

Itemized list of fees charged by each node.

nodesobjectrequired

Fees charged by each node participating in the payment.

property name*Array of objectsadditional property

total_feesArray of objectsrequired

Total fees charged in the payment, separated by currency.

total_feenumberrequired

total value of fee

fee_currencystringrequired

currency of the fee charged

ripplenet_infoArray of objects

Application-provided data explaining actions taken by RippleNet applications.

node_addressstringrequired

RippleNet address of the node from which the RippleNetInfo originated.

Example: "rn.us.ny.new_york"

settlement_declinedArray of objectsrequired

If applicable, provides an array of RippleNetInfoEntry's explaining transitions into the SETTLEMENT_DECLINED state

infostring

Information explaining the action taken by a RippleNet application. Could be a RippleNet error code, or a written explanation of the action taken

Example: "L001"

created_atstring(date-time)

The DateTime that this quote was created, as an ISO-8601 timestamp in UTC.

Example: "2018-04-06T20:33:35Z"

execution_conditionstringrequired

A Base64-encoded execution condition for this payment, the fulfillment of which will be presented to the validator to complete this payment. This value must match the execution_condition in the associated crypto transaction.

Example: "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}"

crypto_transaction_idstringrequired

Unique identifier of the crypto transaction associated with this payment.

Example: "4e05da26-7872-4a1f-b9b7-db7604757c37"

validatorstringrequired

Address of the validator that validated the payment.

Example: "rn.us.ca.san_francisco"

payment_typestringrequired

Payment type.

Enum"REGULAR""RETURN"

Example: "REGULAR"

returns_payment_with_idstring(uuid)required

If the payment_type is RETURN, provides the payment ID of the original payment that this payment returns. Otherwise, this field value is set to null.

returned_by_payment_with_idstring(uuid)required

If the payment_type is REGULAR and the payment has an associated return payment, provides the payment ID of the return payment. Otherwise, this field value is set to null.

execution_resultsArray of objectsrequired

Represents the actual movement of funds in a payment. Each execution result corresponds to a quote element and represents its execution in a payment.

execution_result_idstring(uuid)required

Unique identifier for this payment result.

Example: "06f6d4e2-3523-4d17-92fd-53192a06207f"

execution_timestampstring(date-time)required

Date and time at which this portion of the payment was executed, as an ISO-8601 timestamp in UTC.

Example: "2019-10-01T18:24:29.867Z"

execution_result_typestringrequired

Type of payment execution result.<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>

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

Example: "TRANSFER"

execution_result_orderintegerrequired

Order in which the payment execution action was taken along the liquidity path. For example, a payment may include five execution results along the liquidity path. Each execution result has an order number that indicates the order in which the execution result was achieved to make the payment.

Example: 1

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: "trans_usd_sf@rn.us.ca.san_francisco"

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: "conct_usd_sf@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 498

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 498

sending_feenumberrequired

Fees the sender is charging.

Example: 2

receiving_feenumberrequired

Fees the receiver is charging.

Example: 0

sending_currency_codestring

Currency code of the sending amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "USD"

receiving_currency_codestring

Currency of the receiving amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "GBP"

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 of the transfer. Returned in execution results with execute_result_type set to TRANSFER.

intermediary_deltanumber

Amount of XRP representing the difference in FX rate between the moment of quoting and the moment of execution. A positive value is the amount taken out of the incentive pool. A negative value is the amount returned to the incentive pool. (Soon to be deprecated)

Example: 0.2

incentive_typestring

Configuration of the incentive pool on the xRapid side. Two values are supported, firm and fx. For firm, xRapid guarantees that the FX rate at the moment of execution is the same as at the moment of quoting. For fx, xRapid guaratees a predefined FX rate.

Example: "firm"

incentive_valuenumber

Example: 0.2

transaction_hashstring

Hash representing the unique identifier for the transfer of funds in the XRP ledger.

Example: 5.5467794184785867e+76

venue_idstring

The id from an exchange associated with a transaction involving an exchange account.

Example: "nz7RpAujYgnQtjEM"

fiat_adjusted_valuenumber

Represents the delta between quoted and received executed amounts, for exchange trades.

Example: 0.02

odl_payment_idstring

Payment ID in On-Demand Liquidity (ODL) for an executed ODL payment containing the transaction represented by this execution result.

liquidation_execution_resultsArray of objects

Represents the actual movement of funds in a payment as part of liquidation of a Wallet Receive payment.

execution_result_idstring(uuid)required

Unique identifier for this payment result.

Example: "06f6d4e2-3523-4d17-92fd-53192a06207f"

execution_timestampstring(date-time)required

Date and time at which this portion of the payment was executed, as an ISO-8601 timestamp in UTC.

Example: "2019-10-01T18:24:29.867Z"

execution_result_typestringrequired

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

Example: "TRANSFER"

execution_result_orderintegerrequired

Example: 1

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: "trans_usd_sf@rn.us.ca.san_francisco"

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: "conct_usd_sf@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 498

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 498

sending_feenumberrequired

Fees the sender is charging.

Example: 2

receiving_feenumberrequired

Fees the receiver is charging.

Example: 0

sending_currency_codestring

Currency code of the sending amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "USD"

receiving_currency_codestring

Currency of the receiving amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "GBP"

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 of the transfer. Returned in execution results with execute_result_type set to TRANSFER.

intermediary_deltanumber

Example: 0.2

incentive_typestring

Example: "firm"

incentive_valuenumber

Example: 0.2

transaction_hashstring

Hash representing the unique identifier for the transfer of funds in the XRP ledger.

Example: 5.5467794184785867e+76

venue_idstring

The id from an exchange associated with a transaction involving an exchange account.

Example: "nz7RpAujYgnQtjEM"

fiat_adjusted_valuenumber

Represents the delta between quoted and received executed amounts, for exchange trades.

Example: 0.02

odl_payment_idstring

Payment ID in On-Demand Liquidity (ODL) for an executed ODL payment containing the transaction represented by this execution result.

liquidation_detailsobject

Payment liquidation details

idstring(uuid)

Liquidation ID, unique to the liquidation process of this payment

statusstring

Liquidation status

failure_reasonstring

Reason behind failure of the liquidation, only applicable if the status is failure

failure_countinteger

Number of times the liquidation failed. Irrelevant if status is successful.

push_forward_execution_resultsArray of objects

Represents the movement of funds after an On-Demand Liquidity payment fails at intermediary transfer or destination exchange.

execution_result_idstring(uuid)required

Unique identifier for this payment result.

Example: "06f6d4e2-3523-4d17-92fd-53192a06207f"

execution_timestampstring(date-time)required

Date and time at which this portion of the payment was executed, as an ISO-8601 timestamp in UTC.

Example: "2019-10-01T18:24:29.867Z"

execution_result_typestringrequired

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

Example: "TRANSFER"

execution_result_orderintegerrequired

Example: 1

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: "trans_usd_sf@rn.us.ca.san_francisco"

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: "conct_usd_sf@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 498

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 498

sending_feenumberrequired

Fees the sender is charging.

Example: 2

receiving_feenumberrequired

Fees the receiver is charging.

Example: 0

sending_currency_codestring

Currency code of the sending amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "USD"

receiving_currency_codestring

Currency of the receiving amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "GBP"

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 of the transfer. Returned in execution results with execute_result_type set to TRANSFER.

intermediary_deltanumber

Example: 0.2

incentive_typestring

Example: "firm"

incentive_valuenumber

Example: 0.2

transaction_hashstring

Hash representing the unique identifier for the transfer of funds in the XRP ledger.

Example: 5.5467794184785867e+76

venue_idstring

The id from an exchange associated with a transaction involving an exchange account.

Example: "nz7RpAujYgnQtjEM"

fiat_adjusted_valuenumber

Represents the delta between quoted and received executed amounts, for exchange trades.

Example: 0.02

odl_payment_idstring

Payment ID in On-Demand Liquidity (ODL) for an executed ODL payment containing the transaction represented by this execution result.

accepted_atstring(date-time)required

Date and time at which the payment was last accepted, as an ISO-8601 timestamp in UTC.

Example: "2019-10-01T18:25:47.347Z"

locked_atstring(date-time)

Date and time at which the payment was last locked, as an ISO-8601 timestamp in UTC.

Example: "2019-10-01T18:25:47.347Z"

executed_atstring(date-time)

Date and time at which the payment was last executed, as an ISO-8601 timestamp in UTC.

Example: "2019-10-01T18:25:47.347Z"

completed_atstring(date-time)

Date and time at which the payment was last completed, as an ISO-8601 timestamp in UTC.

Example: "2019-10-01T18:25:47.347Z"

returned_atstring(date-time)

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

Example: "2019-10-01T18:25:47.347Z"

internal_infoobjectrequired

JSON object containing information that only the RippleNet instance that set it can view. These values can be set by the sender when accepting a payment and by an intermediary or receiver when locking the payment.

connector_rolestringrequired

Role of the RippleNet node that sets one or more values in the Internal Info object.

Use as follows:

SENDING: Sending account in the payment resides on this RippleNet instance.
RECEIVING: Receiving account in the payment resides on this RippleNet instance.
INTERMEDIARY: Neither sending nor receiving accounts in the payment reside on this RippleNet instance.
INTERNAL: Both sending and receiving accounts in the payment (usually between RippleNet Cloud and RippleNet) reside on this RippleNet instance.

Enum"SENDING""RECEIVING""INTERMEDIARY""INTERNAL"

Example: "RECEIVING"

labelsArray of objectsrequired

Array of objects that provide label values that are set by including the sub_state field at any stage of the payment's lifecycle. Labels can used as a filtering mechanism when searching for payments. Labels are visible only to the node that added them to this copy of a payment. If the values that populate this array are not set in the request or if the values set in the request are not viewable by your node, this array is empty.

labelstring

Label to be attached

internal_idstringrequired

ID that is viewable only to the node that set it. This value can be set by the sender when accepting a payment. This value can also be set by any intermediary and the receiver when locking the payment. If this value is not set in the request or if the value set in the request is not viewable by your node, this field value is set to null.

user_infoArray of objectsrequired

User-provided data with arbitrary key/value pairs.

node_addressstringrequired

RippleNet address of the node that provided the user information.

Example: "rn.us.ca.san_francisco"

acceptedArray of objectsrequired

User information optionally provided when accepting the payment.

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

lockedArray of objectsrequired

User information optionally provided when locking the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

lock_declinedArray of objectsrequired

User information optionally provided when declining to lock the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

retry_acceptArray of objectsrequired

User information optionally provided when retrying acceptance of the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

retry_settlementArray of objectsrequired

User information optionally provided when retrying settlement of the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

settlementArray of objectsrequired

User information optionally provided when settling the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

settlement_declinedArray of objectsrequired

User information optionally provided when settlement for the payment is declined. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

failedArray of objectsrequired

User information optionally provided when failing the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

executedArray of objectsrequired

Payment sub-state information provided using sub_state and memo fields when finalizing the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

completedArray of objectsrequired

User information optionally provided when completing the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

forwardedArray of objectsrequired

If applicable, user information optionally provided when forwarding the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

returnedArray of objectsrequired

If applicable, information optionally provided using return_reasons when returning the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

Response

application/json

{
  "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  "payment_state": "COMPLETED",
  "modified_at": "2019-10-01T18:25:47.347Z",
  "contract": {
    "sender_end_to_end_id": "string",
    "created_at": "2019-10-01T18:18:13.665Z",
    "expires_at": "2019-10-01T18:55:22.824Z",
    "quote": { … },
    "fee_info": { … }
  },
  "ripplenet_info": [
    { … }
  ],
  "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  "validator": "rn.us.ca.san_francisco",
  "payment_type": "REGULAR",
  "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  "execution_results": [
    { … }
  ],
  "liquidation_execution_results": [
    { … }
  ],
  "liquidation_details": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "string",
    "failure_reason": "string",
    "failure_count": 0
  },
  "push_forward_execution_results": [
    { … }
  ],
  "accepted_at": "2019-10-01T18:25:47.347Z",
  "locked_at": "2019-10-01T18:25:47.347Z",
  "executed_at": "2019-10-01T18:25:47.347Z",
  "completed_at": "2019-10-01T18:25:47.347Z",
  "returned_at": "2019-10-01T18:25:47.347Z",
  "internal_info": {
    "connector_role": "RECEIVING",
    "labels": [ … ],
    "internal_id": "string"
  },
  "user_info": [
    { … }
  ]
}

Get quotes

Request

Gets a list of quotes.

Security

Bearer

Query

pageinteger

The page number for paginated results. The value is zero-based, where 0 represents the first page. Set it to 0 to get the first page of results.

Default 0

sizeinteger[ 1 .. 100 ]

Number of objects to return per page.

Default 20

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/quotes?page=0&size=20' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully returned array of quotes.

Bodyapplication/jsonArray [

quote_idstring(uuid)required

Unique identifier for the quote.

Example: "2a547e56-4aac-4375-86a8-8b3e7014801d"

created_atstring(date-time)required

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

Example: "2020-01-29T20:59:44.925Z"

expires_atstring(date-time)required

Date and time after which the quote and its pricing expire, as an ISO-8601 timestamp in UTC.

Default "300s/300000ms"

Example: "2020-01-29T21:29:44.925Z"

typestringrequired

Indicates how the amount field should be treated for calculating quote values.

Enum"SENDER_AMOUNT""RECEIVER_AMOUNT""SENDER_INSTITUTION_AMOUNT""RECEIVER_INSTITUTION_AMOUNT""REVERSAL_AMOUNT"

Example: "SENDER_AMOUNT"

price_guaranteestringrequired

Default "FIRM"

Example: "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: "sf@rn.us.ca.san_francisco"

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: "sf_gbp@rn.us.ca.san_francisco"

amountstringrequired

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

Example: "1"

currency_codestringrequired

Currency code for the amount value.

Example: "USD"

currency_code_filterstringrequired

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: "259189e7-cb14-42e7-99ef-375f3285e356"

quote_element_typestringrequired

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

Example: "EXCHANGE"

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.

Example: "1"

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: "sf@rn.us.ca.san_francisco"

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: "sf_gbp@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 1

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 355

sending_feenumberrequired

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

Example: 0

receiving_feenumberrequired

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

Example: 0

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: "GBP"

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

Payout method for the quote.

Example: "LOCAL_RAILS"

payment_method_fieldsstring

JSON object containing payment method metadata.

Example: "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}"

payout_method_infoobject

Details about the payout method.

payout_method_namestring

Payout method for the quote.

Example: "Cash Payout"

payout_method_categorystring

Category of the payout method. Defaults to <code>OTHER</code> if not specified.

Enum"REAL_TIME_GROSS_SETTLEMENT_SYSTEM""REAL_TIME_NET_SETTLEMENT_SYSTEM""MASS_NET_PAYMENT_SYSTEM""BOOK_TRANSFER""CASH_PAYOUT""WALLET_PAYMENT""OTHER"

Example: "BOOK_TRANSFER"

descriptionstring

User defined description of the payout method.

Example: "local rails"

estimated_time_to_creditstring

The estimated time to credit the beneficiary using this payout method.

Example: "3 days"

]

Response

application/json

[
  {
    "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
    "created_at": "2020-01-29T20:59:44.925Z",
    "expires_at": "2020-01-29T21:29:44.925Z",
    "type": "SENDER_AMOUNT",
    "price_guarantee": "FIRM",
    "sender_address": "sf@rn.us.ca.san_francisco",
    "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
    "amount": "1",
    "currency_code": "USD",
    "currency_code_filter": "EUR",
    "service_type": "string",
    "quote_elements": [ … ],
    "liquidity_warning": "string",
    "payment_method": "LOCAL_RAILS",
    "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
    "payout_method_info": { … }
  }
]

Get quote by quote ID

Request

Gets a quote by ID.

Security

Bearer

Path

quote_idstring(uuid)required

Unique identifier of the quote you want to retrieve.

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/quotes/{quote_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully retrieved quote.

Bodyapplication/json

quote_idstring(uuid)required

Unique identifier for the quote.

Example: "2a547e56-4aac-4375-86a8-8b3e7014801d"

created_atstring(date-time)required

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

Example: "2020-01-29T20:59:44.925Z"

expires_atstring(date-time)required

Date and time after which the quote and its pricing expire, as an ISO-8601 timestamp in UTC.

Default "300s/300000ms"

Example: "2020-01-29T21:29:44.925Z"

typestringrequired

Indicates how the amount field should be treated for calculating quote values.

Enum"SENDER_AMOUNT""RECEIVER_AMOUNT""SENDER_INSTITUTION_AMOUNT""RECEIVER_INSTITUTION_AMOUNT""REVERSAL_AMOUNT"

Example: "SENDER_AMOUNT"

price_guaranteestringrequired

Default "FIRM"

Example: "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: "sf@rn.us.ca.san_francisco"

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: "sf_gbp@rn.us.ca.san_francisco"

amountstringrequired

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

Example: "1"

currency_codestringrequired

Currency code for the amount value.

Example: "USD"

currency_code_filterstringrequired

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: "259189e7-cb14-42e7-99ef-375f3285e356"

quote_element_typestringrequired

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

Example: "EXCHANGE"

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.

Example: "1"

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: "sf@rn.us.ca.san_francisco"

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: "sf_gbp@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 1

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 355

sending_feenumberrequired

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

Example: 0

receiving_feenumberrequired

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

Example: 0

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: "GBP"

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

Payout method for the quote.

Example: "LOCAL_RAILS"

payment_method_fieldsstring

JSON object containing payment method metadata.

Example: "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}"

payout_method_infoobject

Details about the payout method.

payout_method_namestring

Payout method for the quote.

Example: "Cash Payout"

payout_method_categorystring

Category of the payout method. Defaults to <code>OTHER</code> if not specified.

Enum"REAL_TIME_GROSS_SETTLEMENT_SYSTEM""REAL_TIME_NET_SETTLEMENT_SYSTEM""MASS_NET_PAYMENT_SYSTEM""BOOK_TRANSFER""CASH_PAYOUT""WALLET_PAYMENT""OTHER"

Example: "BOOK_TRANSFER"

descriptionstring

User defined description of the payout method.

Example: "local rails"

estimated_time_to_creditstring

The estimated time to credit the beneficiary using this payout method.

Example: "3 days"

Response

application/json

{
  "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
  "created_at": "2020-01-29T20:59:44.925Z",
  "expires_at": "2020-01-29T21:29:44.925Z",
  "type": "SENDER_AMOUNT",
  "price_guarantee": "FIRM",
  "sender_address": "sf@rn.us.ca.san_francisco",
  "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
  "amount": "1",
  "currency_code": "USD",
  "currency_code_filter": "EUR",
  "service_type": "string",
  "quote_elements": [
    { … }
  ],
  "liquidity_warning": "string",
  "payment_method": "LOCAL_RAILS",
  "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
  "payout_method_info": {
    "payout_method_name": "Cash Payout",
    "payout_method_category": "BOOK_TRANSFER",
    "description": "local rails",
    "estimated_time_to_credit": "3 days"
  }
}

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 type	Amount
SENDER_AMOUNT	Amount to be sent by the payment originator
SENDER_INSTITUTION_AMOUNT	Set to `SENDER_INSTITUTION_AMOUNT` to calculate the quote based on the amount to be sent, plus any fees collected by the sending institution
RECEIVER_AMOUNT	Amount to be received by the payment beneficiary
RECEIVER_INSTITUTION_AMOUNT	Set 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 type	Currency code description
SENDER_AMOUNT	Specify the currency code for the sending currency, for example `USD`
SENDER_INSTITUTION_AMOUNT	Specify the currency code for the sending currency, for example `USD`
RECEIVER_AMOUNT	Specify the currency code for the receiving currency, for example `USD`
RECEIVER_INSTITUTION_AMOUNT	Specify the currency code for the receiving currency, for example `USD`

Example: "USD"

quote_typestringrequired

Specifies how to calculate the quote.

Example: SENDER_AMOUNT

Enum Value	Description
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. <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>

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 Value	Description
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 Value	Description
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/reference/openapi/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: "4711728c-cd35-49ec-96a5-72732b4333ec"

quotesArray of objectsrequired

For more information on quote elements, see Create quote collections.

quote_idstring(uuid)required

Unique identifier for the quote.

Example: "2a547e56-4aac-4375-86a8-8b3e7014801d"

created_atstring(date-time)required

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

Example: "2020-01-29T20:59:44.925Z"

expires_atstring(date-time)required

Date and time after which the quote and its pricing expire, as an ISO-8601 timestamp in UTC.

Default "300s/300000ms"

Example: "2020-01-29T21:29:44.925Z"

typestringrequired

Indicates how the amount field should be treated for calculating quote values.

Enum"SENDER_AMOUNT""RECEIVER_AMOUNT""SENDER_INSTITUTION_AMOUNT""RECEIVER_INSTITUTION_AMOUNT""REVERSAL_AMOUNT"

Example: "SENDER_AMOUNT"

price_guaranteestringrequired

Default "FIRM"

Example: "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: "sf@rn.us.ca.san_francisco"

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: "sf_gbp@rn.us.ca.san_francisco"

amountstringrequired

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

Example: "1"

currency_codestringrequired

Currency code for the amount value.

Example: "USD"

currency_code_filterstringrequired

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: "259189e7-cb14-42e7-99ef-375f3285e356"

quote_element_typestringrequired

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

Example: "EXCHANGE"

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.

Example: "1"

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: "sf@rn.us.ca.san_francisco"

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: "sf_gbp@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 1

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 355

sending_feenumberrequired

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

Example: 0

receiving_feenumberrequired

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

Example: 0

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: "GBP"

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

Payout method for the quote.

Example: "LOCAL_RAILS"

payment_method_fieldsstring

JSON object containing payment method metadata.

Example: "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}"

payout_method_infoobject

Details about the payout method.

payout_method_namestring

Payout method for the quote.

Example: "Cash Payout"

payout_method_categorystring

Category of the payout method. Defaults to <code>OTHER</code> if not specified.

Enum"REAL_TIME_GROSS_SETTLEMENT_SYSTEM""REAL_TIME_NET_SETTLEMENT_SYSTEM""MASS_NET_PAYMENT_SYSTEM""BOOK_TRANSFER""CASH_PAYOUT""WALLET_PAYMENT""OTHER"

Example: "BOOK_TRANSFER"

descriptionstring

User defined description of the payout method.

Example: "local rails"

estimated_time_to_creditstring

The estimated time to credit the beneficiary using this payout method.

Example: "3 days"

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": "4711728c-cd35-49ec-96a5-72732b4333ec",
  "quotes": [
    { … }
  ],
  "quote_errors": [
    { … }
  ]
}

Get quote collection by ID

Request

Gets a quote collection that was created for a proposed payment.

Security

Bearer

Path

quote_collection_idstring(uuid)required

The ID of the quote collection you want returned.

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/quote_collections/{quote_collection_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully returned a quote collection.

Bodyapplication/json

quote_collection_idstring(uuid)required

Unique identifier of the quote collection.

Example: "4711728c-cd35-49ec-96a5-72732b4333ec"

quotesArray of objectsrequired

For more information on quote elements, see Create quote collections.

quote_idstring(uuid)required

Unique identifier for the quote.

Example: "2a547e56-4aac-4375-86a8-8b3e7014801d"

created_atstring(date-time)required

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

Example: "2020-01-29T20:59:44.925Z"

expires_atstring(date-time)required

Date and time after which the quote and its pricing expire, as an ISO-8601 timestamp in UTC.

Default "300s/300000ms"

Example: "2020-01-29T21:29:44.925Z"

typestringrequired

Indicates how the amount field should be treated for calculating quote values.

Enum"SENDER_AMOUNT""RECEIVER_AMOUNT""SENDER_INSTITUTION_AMOUNT""RECEIVER_INSTITUTION_AMOUNT""REVERSAL_AMOUNT"

Example: "SENDER_AMOUNT"

price_guaranteestringrequired

Default "FIRM"

Example: "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: "sf@rn.us.ca.san_francisco"

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: "sf_gbp@rn.us.ca.san_francisco"

amountstringrequired

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

Example: "1"

currency_codestringrequired

Currency code for the amount value.

Example: "USD"

currency_code_filterstringrequired

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: "259189e7-cb14-42e7-99ef-375f3285e356"

quote_element_typestringrequired

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

Example: "EXCHANGE"

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.

Example: "1"

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: "sf@rn.us.ca.san_francisco"

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: "sf_gbp@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 1

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 355

sending_feenumberrequired

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

Example: 0

receiving_feenumberrequired

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

Example: 0

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: "GBP"

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

Payout method for the quote.

Example: "LOCAL_RAILS"

payment_method_fieldsstring

JSON object containing payment method metadata.

Example: "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}"

payout_method_infoobject

Details about the payout method.

payout_method_namestring

Payout method for the quote.

Example: "Cash Payout"

payout_method_categorystring

Category of the payout method. Defaults to <code>OTHER</code> if not specified.

Enum"REAL_TIME_GROSS_SETTLEMENT_SYSTEM""REAL_TIME_NET_SETTLEMENT_SYSTEM""MASS_NET_PAYMENT_SYSTEM""BOOK_TRANSFER""CASH_PAYOUT""WALLET_PAYMENT""OTHER"

Example: "BOOK_TRANSFER"

descriptionstring

User defined description of the payout method.

Example: "local rails"

estimated_time_to_creditstring

The estimated time to credit the beneficiary using this payout method.

Example: "3 days"

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": "4711728c-cd35-49ec-96a5-72732b4333ec",
  "quotes": [
    { … }
  ],
  "quote_errors": [
    { … }
  ]
}

Rates

Use these operations to manage your rates.

Operation	Method	Description
Get rates	GET	Gets a list of configured exchange rates.
Create rate	POST	Creates an exchange rate for a specified currency pair.
Get rate by ID	GET	Gets a configured exchange rate by ID.
Update rate	PUT	Updates an existing exchange rate.
Delete rate	DELETE	Deletes an exchange rate. Once deleted, an exchange rate cannot be accessed.

Operations

Request for payment

Use these operations to interact with your payment requests.

Operation	Method	Description
Get requests for payment	GET	Gets requests for payment that match the query parameters.
Send request for payment	POST	Sends a new request for payment.
Get request for payment by ID	GET	Gets a request for payment by request for payment ID.
Accept request for payment	POST	Accepts a request for payment.
Fail request for payment	POST	Fails a request for payment.

Operations

Transfers

Use these operations to manage your transfers.

Operation	Method	Description
Get transfers	GET	Gets a list of transfers.
Get transfer estimate	GET	Get an estimate of the fee to make an "outbound" transfer from an exchange (connected to xRapid) to an another account outside of RippleNet (such as a bank account).
Get transfer by ID	GET	Gets a transfer by ID.
Execute transfer	POST	Transfers funds between accounts.
Complete transfer	POST	Updates the state of a transfer to `COMPLETED`.
Add transfer labels	PUT	Adds a list of labels to the transfer. To retrieve transfers by label, see Get transfers
Delete transfer labels	DELETE	Deletes one or more existing labels from the transfer.

Operations

RippleNet Server API (4.0.0)

Authentication

API environments

Auditing

Balances and statements

Beneficiary confirmation

Diagnostics

Exchange transfers

Fees

Non-orchestration payments

Orchestration payments

Payment expiration

Payout method

Platform accounts

Pool accounts

Quote expiration

Quotes

Accept quote

Request

Responses

Was this page helpful?

Get quotes

Request

Responses

Was this page helpful?

Get quote by quote ID

Request

Responses

Was this page helpful?

Create quote collection

Request

Responses

Was this page helpful?

Get quote collection by ID

Request

Responses

Was this page helpful?

Rates

Request for payment

Transfers

RippleNet Server API (4.0.0)

Authentication

API environments

Auditing

Balances and statements

Beneficiary confirmation

Diagnostics

Exchange transfers

Fees

Non-orchestration payments

Orchestration payments

Payment expiration

Payout method

Platform accounts

Pool accounts

Quote expiration

Quotes

Accept quote

Request

Responses

Was this page helpful?

Get quotes

Request

Responses

Was this page helpful?

Get quote by quote ID

Request

Responses

Was this page helpful?

Create quote collection

RequestExpand all

Responses

Was this page helpful?

Get quote collection by ID

Request

Responses

Was this page helpful?

Rates

Request for payment

Transfers

Request