Create quote to reverse payment

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`

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

Create quote to return payment

Request

Creates a collection of quotes that can be used to return a payment.

The receiver can make this request while the payment is in states EXECUTED, COMPLETED, or FAILED. When the returned payment is successfully moved to the COMPLETED state, the original payment is moved to the RETURNED state.

Note: Currently, when making a Return Payment to a RippleNet Cloud account on a RippleNet ledger, the RippleNet user must lock and complete the payment. This means that the RippleNet user takes all action on the return: Get and Accept Quote, Lock, Settle, and Complete payment.

Security

Bearer

Bodyapplication/jsonrequired

original_payment_idstring(uuid)required

ID of the original payment to be returned.

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

return_reasonsobject

Object with key and value pairs that describe the reason the payment is being returned.

The fields should contain the following key values: reason, code, and type.

These values are included in a payment created from a quote in the response. They are included in the user_info.returned array for the node sending the return payment.

Example: {"REASON":"Wrong receiving amount","TYPE":"Account Error","CODE":"A-999"}

return_amount_typestring

Amount type of the return payment.To indicate that the sender of the return payment will send the amount it received, set to TOTAL_RECEIVED.To indicate that the sender of the return payment will send the amount it received minus its receiving fees, set to TOTAL_RECEIVED_MINUS_FEES.

Default "TOTAL_RECEIVED"

Enum"TOTAL_RECEIVED""TOTAL_RECEIVED_MINUS_FEES"

Example: "TOTAL_RECEIVED_MINUS_FEES"

custom_feenumber

Custom fee charged and collected by the sending account. Setting this field overrides all applicable 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"

force_path_finding_and_liquidity_path_findingboolean

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

Default false

Example: false

receiver_addressstring

The desired receiving account for the return payment as a RippleNet address. This account must be owned by the original payment's sender.

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

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/quote_collections/return \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "original_payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
    "return_reasons": {
      "REASON": "Wrong receiving amount",
      "TYPE": "Account Error",
      "CODE": "A-999"
    },
    "return_amount_type": "TOTAL_RECEIVED_MINUS_FEES",
    "custom_fee": 0,
    "custom_rate": {
      "rate": 0,
      "base_currency": "string",
      "counter_currency": "string",
      "rate_type": "buy"
    },
    "force_path_finding_and_liquidity_path_finding": false,
    "receiver_address": "sf@rn.us.ca.san_francisco"
  }'

Responses

Successfully returned a collection of quotes to return a payment.

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

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.

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": [
    { … }
  ]
}

Create quote to reverse payment

Request

Creates a quote collection containing at most one quote that can be used to reverse a payment.

The receiver can make this request while the payment is in states EXECUTED, COMPLETED, or FAILED. When the returned payment is successfully moved to the COMPLETED state, the original payment is moved to the RETURNED state.

Note: Currently, when making a Reversal Payment to a RippleNet Cloud account on a RippleNet ledger, the RippleNet user must lock and complete the payment. This means that the RippleNet user takes all action on the reverse: Get and Accept Quote, Lock, Settle, and Complete payment.

Security

Bearer

Bodyapplication/jsonrequired

original_payment_idstring(uuid)required

ID of the original payment to be reversed.

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

reversal_reasonobjectrequired

A structured object detailing reasons for a payment reversal.

codestringrequired

The code indicating the reason for payment reversal. For code descriptions and error handling information, see Returns and failure codes.

Enum"RB001""RB002""RB003""RB004""RB005""RB008""RB009""RB010""RB011""RB012"

Example: "RB001"

descriptionstring

Optional. User-defined string describing the reason for payment reversal. When using the reversal reason code NARR (Narrative), you must specify the reason for the return in the reversal_reason object's description attribute.

Example: "No account / Unable to locate account"

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/quote_collections/reversal \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "original_payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
    "reversal_reason": {
      "code": "RB001",
      "description": "No account / Unable to locate account"
    }
  }'

Responses

Successfully returned a collection of quotes to return a payment.

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

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.

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": [
    { … }
  ]
}

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

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

RippleNet Server API (4.0.0)

Authentication

API environments

Account configuration

Auditing

Balances and statements

Beneficiary confirmation

Diagnostics

Exchange transfers

Fees

Liquidation configuration

Non-orchestration payments

Create quote to return payment

RequestExpand all

Responses

Was this page helpful?

Create quote to reverse payment

RequestExpand all

Responses

Was this page helpful?

Notifications

ODL flags configuration

Orchestration payments

Payment expiration

Payout method

Platform accounts

Pool accounts

Quote expiration

Quotes

Rates

Request for payment

Sender segregated account configuration

Transfers

schema

activity

Orchestration Template

diagnostics

payment

Get application info

Request

Responses

Was this page helpful?

tenant

Orchestration internal action

Orchestration internal payments

Orchestration internal notifications

Request

Request