Get orchestration notifications by unique reference number

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`

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

Create orchestration payment

Request

Creates an orchestration payment.

Security

Bearer

Bodyapplication/jsonrequired

sender_end_to_end_idstring[ 1 .. 64 ] characters^[a-zA-Z0-9@_,:\s-]*$required

Unique ID that the sender can specify.

Persisted on all instances that participate in the payment.

internal_idstring[ 1 .. 64 ] characters^[a-zA-Z0-9@_,:\s-]*$

[Sender only]

Internal ID that the sender can optionally specify.

Only visible to the sender. Only the sending RippleNet instance stores this ID.

orchestration_templatestring[ 1 .. 64 ] characters^[a-zA-Z0-9_-]*$

Parameter for the orchestration template name.

If you don't specify a template name, a default template will be picked.

sending_addressstring[ 1 .. 256 ] characters^([\.a-zA-Z0-9_~-]+@)?(rn|dev|test|uat)([.][a...required

RippleNet account name and address of the sender.

Format: accountname@ripplenetaddress

Example: new_york@rn.us.ny.new_york

receiving_addressstring[ 1 .. 256 ] characters^([\.a-zA-Z0-9_~-]+@)?(rn|dev|test|uat)([.][a...required

RippleNet account name and address of the receiver.

Format: accountname@ripplenetaddress

Example: new_york@rn.us.ny.new_york

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

currencystring= 3 charactersrequired

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= 3 characters

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

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

Custom rate that the return payment quotes must use.

ratenumberrequired

Exchange rate for a base and counter currency.

base_currencystring= 3 charactersrequired

Base currency of the exchange rate.

counter_currencystring= 3 charactersrequired

Counter currency of the exchange rate.

rate_typestringrequired

Order type for the exchange rate.

Valid values are sell or buy.

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[ 2 .. 32 ] characters^[a-zA-Z0-9@_,:\s-]*$

Use this field, when using ODL, to indicate the type of fees to apply.

When testing, set "payment_method": "none" to ensure funds remain at the destination exchange and are not paid out to a local rail.

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.

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"

user_infoobjectrequired

Provide one or more arbitrary key/value pairs.

sender_segregated_accountstring

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.

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/v4/orchestration/payment \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sender_end_to_end_id": "string",
    "internal_id": "string",
    "orchestration_template": "string",
    "sending_address": "string",
    "receiving_address": "string",
    "amount": "string",
    "currency": "USD",
    "quote_type": "SENDER_AMOUNT",
    "sender_or_receiver_currency": "USD",
    "custom_fee": 0,
    "custom_rate": {
      "rate": 0,
      "base_currency": "str",
      "counter_currency": "str",
      "rate_type": "string"
    },
    "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",
    "user_info": {},
    "sender_segregated_account": "conct_php_receiver_coins_sender@receiver",
    "quote_limit": 0,
    "quote_filter_types": [
      "LIQUIDITY_WARNINGS"
    ]
  }'

Responses

Successfully created orchestration payment.

Bodyapplication/json

sender_end_to_end_idstring

Sender end-to-end ID.

Example: "00310000015"

Response

application/json

{
  "sender_end_to_end_id": "00310000015"
}

Get orchestration payments

Request

Gets a list of orchestration payments.

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.

sizeinteger[ 1 .. 100 ]

Number of objects to return per page.

Default 10

sort_fieldstring

Attribute to sort the results on.

Enum:	Sort by
CREATED_AT	Created date-time
MODIFIED_AT	Modified date-time

Default "MODIFIED_AT"

Enum"CREATED_AT""MODIFIED_AT"

sort_directionstring

Direction of sorted results based on sort_field.

Enum:	Description
ASC	Sort ascending
DESC	Sort descending

Default "ASC"

Enum"ASC""DESC"

unique_reference_numberstring

Parameter for filtering with unique reference number.

orchestration_statusstring

Parameter for filtering with status of the orchestration payment.

Enum	Description
INITIAL	Filter by payments in the initial state
RUNNING	Filter by payments in the running state
COMPLETED	Filter by completed payments
PAUSED	Filter by paused payments
FAILURE	Filter by payment failures
DECLINED	Filter by declined payments
RETRY	Filter by payments that have a retry status

Enum"INITIAL""RUNNING""COMPLETED""PAUSED""FAILURE""DECLINED""RETRY"

range_fieldstring

Range field

Designates the column name of the payments database table that is used for filtering payments before/after/between time stamps.

The following options are valid:

Range field	Description
CREATED_AT	Filter by created date-time
MODIFIED_AT	Filter by modified date-time

Example usage

If you specify range_field = MODIFIED_AT, you need to specify a time stamp (in the 24 character ISO 8601 format used in payment objects: YYYY-MM-DDTHH:mm:ss.sssZ) as the value for before and/or after to fetch payments before, after, or between the specified time range(s) (inclusive).

Dependency: If you specify range_field, you must also specify before and/or after.

beforestring

Before time stamp

Filters for payments where the range_field column value is before this specified time stamp (inclusive).

You can also specify after to create a time range between after and before.

Dependency: If you specify before, you must also specify range_field.

Example: 2023-10-13T10:16:29.000Z

afterstring

After time stamp

Filters for payments where the range_field column value is after this specified time stamp (inclusive).

You can also specify before to create a time range between after and before.

Dependency: If you specify after, you must also specify range_field.

Example: 2023-10-13T10:16:29.000Z

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/v4/orchestration/payment?page=0&size=10&sort_field=CREATED_AT&sort_direction=ASC&unique_reference_number=string&orchestration_status=INITIAL&range_field=string&before=string&after=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully fetched all orchestration payments.

Bodyapplication/json

firstboolean

true if this is the first page.

lastboolean

true if this is the last page.

numberinteger

page number

numberOfElementsinteger

Number Of elements in this request

sizeinteger

page size

totalElementsinteger(int64)

Total number of elements for the given request

totalPagesinteger

Total number of pages for the given request

sortArray of objects

Sort details of this page

directionstring

Direction of the sort

Example: "ASC"

propertystring

ignoreCaseboolean

nullHandlingstring

Example: "NULLS_FIRST"

ascendingboolean

Example: true

descendingboolean

Example: false

contentArray of objects

uuidstring(uuid)

Unique Identifier of the orchestration payment.

Example: "5492648d-2132-4e70-9ded-2fc86f22b321"

unique_reference_numberstring

Unique reference number.

Example: "00310000015"

sender_end_to_end_idstring

Sender end-to-end ID.

Example: "00310000015"

payment_typestring

The payment type for the payment.

Enum"REGULAR""RETURN""REVERSAL"

connector_rolestring

The connector role for payment.

Enum"SENDING""RECEIVING""INTERMEDIARY"

payment_idstring

Payment ID for the transaction in RippleNet.

Example: "26bf269b-1a2b-c3d4-872a-7f18d7dcf9f2"

payment_statusstring

Status of the payment.

Example: "SUCCESS"

previous_payment_statusstring

Previous status of the payment.

Example: "EXECUTED"

orchestration_templatestring

Template name used for executing the orchestration payment.

Example: "default_template"

orchestration_statusstring

Status of the orchestration payment.

Example: "RUNNING"

current_activitystring

Current activity which is being executed.

Example: "get_quote_v1"

current_activity_statusstring

Status of the current activity.

Example: "SUCCESS"

initial_contextobject

Initial context for the orchestration payment.

current_contextobject

Current context of the orchestration payment.

error_messageobject

Error message in case of any error.

activity_listobject

Activity list of the activities executed so far.

created_atstring(date-time)

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

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

modified_atstring(date-time)

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

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

Response

application/json

{
  "first": true,
  "last": true,
  "number": 0,
  "numberOfElements": 0,
  "size": 0,
  "totalElements": 0,
  "totalPages": 0,
  "sort": [
    { … }
  ],
  "content": [
    { … }
  ]
}

Get orchestration payment

Request

Gets orchestration payment by unique reference number.

Security

Bearer

Path

uniqueReferenceNumberstring(String)[ 1 .. 64 ] characters^[a-zA-Z0-9@_,:\s-]*$required

Unique reference number of the orchestration payment to fetch.

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

Responses

Successfully returned orchestration payment.

Bodyapplication/json

uuidstring(uuid)

Unique Identifier of the orchestration payment.

Example: "5492648d-2132-4e70-9ded-2fc86f22b321"

unique_reference_numberstring

Unique reference number.

Example: "00310000015"

sender_end_to_end_idstring

Sender end-to-end ID.

Example: "00310000015"

payment_typestring

The payment type for the payment.

Enum"REGULAR""RETURN""REVERSAL"

connector_rolestring

The connector role for payment.

Enum"SENDING""RECEIVING""INTERMEDIARY"

payment_idstring

Payment ID for the transaction in RippleNet.

Example: "26bf269b-1a2b-c3d4-872a-7f18d7dcf9f2"

payment_statusstring

Status of the payment.

Example: "SUCCESS"

previous_payment_statusstring

Previous status of the payment.

Example: "EXECUTED"

orchestration_templatestring

Template name used for executing the orchestration payment.

Example: "default_template"

orchestration_statusstring

Status of the orchestration payment.

Example: "RUNNING"

current_activitystring

Current activity which is being executed.

Example: "get_quote_v1"

current_activity_statusstring

Status of the current activity.

Example: "SUCCESS"

initial_contextobject

Initial context for the orchestration payment.

current_contextobject

Current context of the orchestration payment.

error_messageobject

Error message in case of any error.

activity_listobject

Activity list of the activities executed so far.

created_atstring(date-time)

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

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

modified_atstring(date-time)

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

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

Response

application/json

{
  "uuid": "5492648d-2132-4e70-9ded-2fc86f22b321",
  "unique_reference_number": "00310000015",
  "sender_end_to_end_id": "00310000015",
  "payment_type": "REGULAR",
  "connector_role": "SENDING",
  "payment_id": "26bf269b-1a2b-c3d4-872a-7f18d7dcf9f2",
  "payment_status": "SUCCESS",
  "previous_payment_status": "EXECUTED",
  "orchestration_template": "default_template",
  "orchestration_status": "RUNNING",
  "current_activity": "get_quote_v1",
  "current_activity_status": "SUCCESS",
  "initial_context": {},
  "current_context": {},
  "error_message": {},
  "activity_list": {},
  "created_at": "2018-04-06T20:33:35Z",
  "modified_at": "2018-04-06T20:33:35Z"
}

Return orchestration payment

Request

Returns the orchestration payment with customer end-to-end ID.

Security

Bearer

Bodyapplication/jsonrequired

sender_end_to_end_idstring[ 1 .. 64 ] characters^[a-zA-Z0-9@_,:\s-]*$required

Unique ID that the sender can specify.

original_payment_idstring[ 1 .. 64 ] characters^[a-zA-Z0-9@_,:\s-]*$required

Unique ID of the payment that should be returned.

return_reasonsobject

Provide one or more arbitrary key/value pairs.

return_amount_typestring

Amount type of the return payment.

Default "TOTAL_RECEIVED"

Enum Value	Description
TOTAL_RECEIVED	Indicates that the sender of the return payment will send the amount they received
TOTAL_RECEIVED_MINUS_FEES	Indicates that the sender of the return payment will send the amount they received minus the receiving 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

Custom rate that the return payment quotes must use.

ratenumberrequired

Exchange rate for a base and counter currency.

base_currencystring= 3 charactersrequired

Base currency of the exchange rate.

counter_currencystring= 3 charactersrequired

Counter currency of the exchange rate.

rate_typestringrequired

Order type for the exchange rate.

Valid values are sell or buy.

force_path_finding_and_liquidity_path_findingboolean

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

Forces performing new path finding and liquidity path finding.

Default false

Example: false

user_infoobject

Provide one or more arbitrary key/value pairs.

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/v4/orchestration/payment/return \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sender_end_to_end_id": "string",
    "original_payment_id": "string",
    "return_reasons": {},
    "return_amount_type": "TOTAL_RECEIVED",
    "custom_fee": 0,
    "custom_rate": {
      "rate": 0,
      "base_currency": "str",
      "counter_currency": "str",
      "rate_type": "string"
    },
    "force_path_finding_and_liquidity_path_finding": false,
    "user_info": {}
  }'

Responses

Successfully returned orchestration payment.

Bodyapplication/json

sender_end_to_end_idstring

Sender end-to-end ID.

Example: "00310000015"

Response

application/json

{
  "sender_end_to_end_id": "00310000015"
}

Accept orchestration payment

Request

Accepts the orchestration payment with customer end-to-end ID and Quote ID.

Security

Bearer

Bodyapplication/jsonrequired

sender_end_to_end_idstring[ 1 .. 64 ] characters^[a-zA-Z0-9@_,:\s-]*$required

Unique ID that the sender can specify.

Persisted on all instances that participate in the payment.

internal_idstring[ 1 .. 64 ] characters^[a-zA-Z0-9@_,:\s-]*$

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

quote_idstring(uuid)required

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

Example: "5492648d-2132-4e70-9ded-2fc86f22b321"

orchestration_templatestring[ 1 .. 64 ] characters^[a-zA-Z0-9_-]*$

Parameter for the orchestration template name.

If you don't provide a template, a default template will be picked.

user_infoobjectrequired

provide one or more arbitrary key/value pairs.

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/v4/orchestration/payment/accept \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sender_end_to_end_id": "string",
    "internal_id": "string",
    "quote_id": "5492648d-2132-4e70-9ded-2fc86f22b321",
    "orchestration_template": "string",
    "user_info": {}
  }'

Responses

Successfully accepted orchestration payment.

Bodyapplication/json

sender_end_to_end_idstring

Sender end-to-end ID.

Example: "00310000015"

Response

application/json

{
  "sender_end_to_end_id": "00310000015"
}

Reverse orchestration payment

Request

Reverses the orchestration payment with customer end-to-end ID.

Security

Bearer

Bodyapplication/jsonrequired

sender_end_to_end_idstring[ 1 .. 64 ] characters^[a-zA-Z0-9@_,:\s-]*$required

Unique ID that the sender can specify.

original_payment_idstring[ 1 .. 64 ] characters^[a-zA-Z0-9@_,:\s-]*$required

Unique ID of the payment that should be reversed.

reversal_reasonobjectrequired

A structured object detailing reasons for a payment reversal.

codestringrequired

The code indicating the reason for payment reversal.

Enum Value	Description
RB001	The account number structure is valid but the account number does not correspond to the individual identified in the payment. <br /><br />This error typically occurs because the Originator specified the Beneficiary's account number incorrectly while initiating the payment.<br/><br/><b>Error handling</b><br/>The Sending Member may introduce prompts in the user interface during payment initiation to ensure that the Originator validates the Beneficiary's account number.
RB002	The Sender has requested Receiver for return of the payment.<br /><br />This error typically occurs in business scenarios where the Originator contacts the Sending Member to indicate that they (the Originator) provided incorrect account information.<br/><br/><b>Error handling</b><br/>The Sending Member must contact the Receiving Member and obtain agreement that the payment should be returned. After obtaining agreement, the Receiving Member can initiate the return of the payment.
RB003	The funds for the payment have not been collected by the Beneficiary within the set period.<br/><br/><b>Error handling</b><br/>The Originator must inform the Beneficiary that they should collect the funds within the prescribed time frame. <br /><br />The Receiving Member may also contact the Beneficiary to inform them of pending or uncollected funds. <br />Further, the Receiving Member must ensure that the Sending Member includes the Beneficiary's contact information in the RippleNet Payment Object.
RB004	Beneficiary's account is frozen due to specific action taken by the Receiver or by legal action. <br /><br /> This error typically occurs when the Beneficiary's bank has frozen the account due to suspected misuse, or on the Beneficiary's request.<br/><br/><b>Error handling</b><br/>The Originator may contact the Beneficiary for alternative account information or to agree on an alternative payment mechanism.
RB005	The Receiver has returned the payment due to one of the following reasons: <br /><br /><ul><li>The exact amount required has not been remitted. </li><li>Acceptance of the transaction results in an overpayment.</li></ul><br/><br/><b>Error handling</b><br/>In case of a technical or human error, the Sending Member or the Originator must adapt their internal RippleNet payment initiation process to ensure they do not transfer the incorrect amount. <br /><br />The Beneficiary may contact the Originator and ask them to initiate a payment for the exact amount.
RB008	Invalid account title or name prefix. <br /><br />This error typically occurs when the Beneficiary's title or name specified in the payment does not match the information associated with their account.<br/><br/><b>Error handling</b><br/>In case of a technical or human error, the Sending Member or the Originator must adapt their internal RippleNet payment initiation process to ensure they do not provide the incorrect Beneficiary title or name. <br /><br />If the Beneficiary provided incorrect information, the Originator may contact the Beneficiary to obtain the correct information.
RB009	Beneficiary's account is dormant. <br /><br />This error typically occurs because the Beneficiary's Bank has marked the account as dormant due to a lack of activity or financial transactions on the account.<br/><br/><b>Error handling</b><br/>The Originator may contact the Beneficiary for alternative account information or to agree upon a different payment mechanism.
RB010	The minimum amount required has not been remitted. <br /><br />This error typically occurs because the Originator has initiated payment for an amount that is lower than the intended amount that they previously agreed upon with the Beneficiary.<br/><br/><b>Error handling</b><br/>In case of technical or human error, the Sending Member or the Originator must adapt their internal RippleNet payment initiation process to ensure they do not specify incorrect amounts.
RB011	The account is subject to litigation. <br /><br />This error typically occurs because the Beneficiary's Bank has frozen the account due to legal reasons, or under suspicion of misuse, or on the Beneficiary's request.<br/><br/><b>Error handling</b><br/>The Originator may contact the Beneficiary for alternative account information or to agree upon a different payment mechanism.
RB012	The Originator is not known to the Recipient or Beneficiary.<br/><br/><b>Error handling</b><br/>In case of technical or human error, the Sending Member or the Originator must adapt their internal RippleNet payment initiation process to ensure they do not initiate payments to unknown or unintended Beneficiary accounts.

Example: "RB001"

descriptionstring

User-defined string describing the reason for payment reversal.

Example: "No account / Unable to locate account"

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/v4/orchestration/payment/reversal \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sender_end_to_end_id": "string",
    "original_payment_id": "string",
    "reversal_reason": {
      "code": "RB001",
      "description": "No account / Unable to locate account"
    }
  }'

Responses

Successfully returned orchestration payment.

Bodyapplication/json

sender_end_to_end_idstring

Sender end-to-end ID.

Example: "00310000015"

Response

application/json

{
  "sender_end_to_end_id": "00310000015"
}

Get orchestration notifications by status

Request

Gets a list of orchestration payment notifications with a given status.

Security

Bearer

Query

statusstringrequired

The 'status' of the notifications to retrieve.

Enum"NEW""SENT"

sizeinteger[ 1 .. 100 ]

Number of objects to return per page.

Default 10

delay_timeinteger

Delay time in minutes to retrieve the SENT notifications.

Default 30

range_fieldstring

Range Field

Designates the column name of the notifications database table that is used for filtering notifications before/after/between time stamps.

The following options are valid:

Range field	Description
CREATED_AT	Filter by created date-time
MODIFIED_AT	Filter by modified date-time

Example usage

If you specify range_field = MODIFIED_AT, you need to specify a time stamp (in the 24 character ISO 8601 format used in notifications objects: YYYY-MM-DDTHH:mm:ss.sssZ) as the value for before and/or after to fetch notifications before, after, or between the specified time range(s) (inclusive).

Dependency: If range_field is specified, before and/or after must also be specified.

beforestring

Before time stamp

Filters for notifications where the notifications range_field column value is before this specified time stamp (inclusive).

You can also specify after to create a time range between after and before.

Dependency: If you specify before, you must also specify range_field.

Example: 2023-10-13T10:16:29.000Z

afterstring

After time stamp

Filters for notifications where the notifications range_field column value is after this specified time stamp (inclusive).

You can also specify before to create a time range between after and before.

Dependency: If you specify after, you must also specify range_field.

Example: 2023-10-13T10:16:29.000Z

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/v4/orchestration/payment/notification?status=NEW&size=10&delay_time=30&range_field=string&before=string&after=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully fetched orchestration payment notifications list.

Bodyapplication/jsonArray [

uuidstring(uuid)

Unique Identifier of the orchestration payment notification.

Example: "5492648d-2132-4e70-9ded-2fc86f22b321"

notification_typestring

Type of the orchestration payment notification.

Example: "PAYMENT_SUCCESS"

notification_versionstring

Version of the orchestration payment notification.

Example: 1

notification_statusstring

Orchestration payment notification status.

Enum"NEW""SENT""ACK"

notification_payloadobject

Orchestration payment notification payload.

created_atstring(date-time)

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

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

modified_atstring(date-time)

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

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

]

Response

application/json

[
  {
    "uuid": "5492648d-2132-4e70-9ded-2fc86f22b321",
    "notification_type": "PAYMENT_SUCCESS",
    "notification_version": 1,
    "notification_status": "NEW",
    "notification_payload": {},
    "created_at": "2018-04-06T20:33:35Z",
    "modified_at": "2018-04-06T20:33:35Z"
  }
]

Get orchestration notifications by unique reference number

Request

Gets orchestration payment notifications with a given unique reference number.

Security

Bearer

Path

uniqueReferenceNumberstring(string)required

The sender_end_to_end_id of the orchestration payment notification in case of sender and payment_id in case of receiver.

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/v4/orchestration/payment/notification/urn/{uniqueReferenceNumber}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully fetched orchestration payment notifications.

Bodyapplication/jsonArray [

uuidstring(uuid)

Unique Identifier of the orchestration payment notification.

Example: "5492648d-2132-4e70-9ded-2fc86f22b321"

notification_typestring

Type of the orchestration payment notification.

Example: "PAYMENT_SUCCESS"

notification_versionstring

Version of the orchestration payment notification.

Example: 1

notification_statusstring

Orchestration payment notification status.

Enum"NEW""SENT""ACK"

notification_payloadobject

Orchestration payment notification payload.

created_atstring(date-time)

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

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

modified_atstring(date-time)

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

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

]

Response

application/json

[
  {
    "uuid": "5492648d-2132-4e70-9ded-2fc86f22b321",
    "notification_type": "PAYMENT_SUCCESS",
    "notification_version": 1,
    "notification_status": "NEW",
    "notification_payload": {},
    "created_at": "2018-04-06T20:33:35Z",
    "modified_at": "2018-04-06T20:33:35Z"
  }
]

Get orchestration notification

Request

Gets a given orchestration payment notification by UUID.

Security

Bearer

Path

uuidstring(uuid)required

The UUID of the orchestration payment notification.

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/v4/orchestration/payment/notification/{uuid}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully fetched orchestration paymnet notification.

Bodyapplication/json

uuidstring(uuid)

Unique Identifier of the orchestration payment notification.

Example: "5492648d-2132-4e70-9ded-2fc86f22b321"

notification_typestring

Type of the orchestration payment notification.

Example: "PAYMENT_SUCCESS"

notification_versionstring

Version of the orchestration payment notification.

Example: 1

notification_statusstring

Orchestration payment notification status.

Enum"NEW""SENT""ACK"

notification_payloadobject

Orchestration payment notification payload.

created_atstring(date-time)

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

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

modified_atstring(date-time)

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

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

Response

application/json

{
  "uuid": "5492648d-2132-4e70-9ded-2fc86f22b321",
  "notification_type": "PAYMENT_SUCCESS",
  "notification_version": 1,
  "notification_status": "NEW",
  "notification_payload": {},
  "created_at": "2018-04-06T20:33:35Z",
  "modified_at": "2018-04-06T20:33:35Z"
}

Acknowledge orchestration notification

Request

Acknowledges an orchestration payment notification with a specified UUID.

Security

Bearer

Path

uuidstring(uuid)required

The UUID of the orchestration payment notification.

curl -i -X PUT \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/v4/orchestration/payment/notification/{uuid}/ack' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully updated orchestration payment notification status.

Bodyapplication/json

uuidstring(uuid)

Unique Identifier of the orchestration payment notification.

Example: "5492648d-2132-4e70-9ded-2fc86f22b321"

notification_typestring

Type of the orchestration payment notification.

Example: "PAYMENT_SUCCESS"

notification_versionstring

Version of the orchestration payment notification.

Example: 1

notification_statusstring

Orchestration payment notification status.

Enum"NEW""SENT""ACK"

notification_payloadobject

Orchestration payment notification payload.

created_atstring(date-time)

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

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

modified_atstring(date-time)

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

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

Response

application/json

{
  "uuid": "5492648d-2132-4e70-9ded-2fc86f22b321",
  "notification_type": "PAYMENT_SUCCESS",
  "notification_version": 1,
  "notification_status": "NEW",
  "notification_payload": {},
  "created_at": "2018-04-06T20:33:35Z",
  "modified_at": "2018-04-06T20:33:35Z"
}

Acknowledge orchestration notifications

Request

Acknowledges multiple orchestration payment notifications using a list of UUIDs.

Security

Bearer

Bodyapplication/jsonrequired

uuidsArray of strings(uuid)non-empty

List of orchestration payment notification UUIDs.

Example: ["328b3e50-7983-46d5-94a0-ef004d78db1d"]

curl -i -X PUT \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/v4/orchestration/payment/notification/ack \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "uuids": [
      "328b3e50-7983-46d5-94a0-ef004d78db1d"
    ]
  }'

Responses

Successfully acknowledged orchestration payment notifications.

Bodyapplication/json

notification_ack_listArray of objects

List of responses of acknowledged orchestration payment notifications.

uuidstring(uuid)

Unique Identifier of the orchestration payment notification.

Example: "5492648d-2132-4e70-9ded-2fc86f22b321"

notification_typestring

Type of the orchestration payment notification.

Example: "PAYMENT_SUCCESS"

notification_versionstring

Version of the orchestration payment notification.

Example: 1

notification_statusstring

Orchestration payment notification status.

Enum"NEW""SENT""ACK"

notification_payloadobject

Orchestration payment notification payload.

created_atstring(date-time)

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

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

modified_atstring(date-time)

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

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

invalid_uuid_listArray of strings(uuid)

Example: ["328b3e50-7983-46d5-94a0-ef004d78db1d"]

Response

application/json

{
  "notification_ack_list": [
    { … }
  ],
  "invalid_uuid_list": [
    "328b3e50-7983-46d5-94a0-ef004d78db1d"
  ]
}

Post action to orchestration payment

Request

Posts action into the Orchestration service.

Security

Bearer

Bodyapplication/jsonrequired

unique_reference_numberstring[ 1 .. 64 ] characters^[a-zA-Z0-9@_,:\s-]*$required

Set to the unique reference number associated with the payment.

Example: "310000015"

statusstringrequired

Activity status

Enum Value	Description
SUCCESS	Set status to success
FAILURE	Set status to failure Use with the `error` field to provide additional information.
DECLINED	Set status to declined Use with the `error` field to provide additional information.
REDO	Set status to redo
SUBSTATE	Set status to substate
NOTIFY	Set status to notify
PENDING	Set status to pending
SUBTASK	Set status to subtask

Example: "SUBSTATE"

notification_typestring[ 1 .. 128 ] characters^[a-zA-Z0-9_:]*$required

Activity context name.

Use with the status parameter to define the action.

Recommended values:

Value	Notification type
CONFIRM_LOCK	Confirm the lock
CONFIRM_SETTLE	Confirm settlement
CONFIRM_COMPLETE	Confirm completion
PARTNER_SUBSTATE	Notify on partner substate<br/><br/>Use with `output.sub_state` to provide additional information.

Example: "PARTNER_SUBSTATE"

outputobject

Use this object when notification_type is PARTNER_SUBSTATE.

For all other values of notification_type, this property can be null.

sub_statestring[ 1 .. 128 ] characters

Free-form string that describes a sub-state of the payment while it is in the EXECUTED state, for example, FORWARDED or AWAITING_COLLECTION.

Displays as a label value in the labels array.

Also displays as the key value in the receiving node's user_info.executed array.

Example: "AMENDED"

memostring

Free-form details that describe the sub_state of the payment, for example, with courier heading to payout location.

Displays as the value value in the receiving node's user_info.executed array.

Example: "Last name must be corrected"

infoobject

Provide one or more arbitrary key/value pairs.

Example: {"last_name":"Gonzales"}

errorArray of objects

Array of one or more activity error objects.

When status is FAILURE or DECLINED, use this to fail a payment or decline a request to lock a payment.

For all other status values, this property can be null.

Example: "null"

typestring

For recommended type values, see Returns and failure codes.

codestring

For recommended failure codes, see Returns and failure codes.

reasonstring

The reason for the failure or lock decline.

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/reference/openapi/v4/orchestration/payment/action \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "unique_reference_number": "310000015",
    "status": "SUBSTATE",
    "notification_type": "PARTNER_SUBSTATE",
    "output": {
      "sub_state": "AMENDED",
      "memo": "Last name must be corrected",
      "info": {
        "last_name": "Gonzales"
      }
    },
    "error": "null"
  }'

Responses

Successfully posted action.

Bodyapplication/json

unique_reference_numberstring

Unique Reference Number.

Example: "00310000015"

Response

application/json

{
  "unique_reference_number": "00310000015"
}

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

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

Create orchestration payment

RequestExpand all

Responses

Was this page helpful?

Get orchestration payments

Request

Responses

Was this page helpful?

Get orchestration payment

Request

Responses

Was this page helpful?

Return orchestration payment

RequestExpand all

Responses

Was this page helpful?

Accept orchestration payment

Request

Responses

Was this page helpful?

Reverse orchestration payment

RequestExpand all

Responses

Was this page helpful?

Get orchestration notifications by status

Request

Responses

Was this page helpful?

Get orchestration notifications by unique reference number

Request

Responses

Was this page helpful?

Get orchestration notification

Request

Responses

Was this page helpful?

Acknowledge orchestration notification

Request

Responses

Was this page helpful?

Acknowledge orchestration notifications

Request

Responses

Was this page helpful?

Post action to orchestration payment

RequestExpand all

Responses

Was this page helpful?

Payment expiration

Payout method

Platform accounts

Pool accounts

Quote expiration

Quotes

Rates

Request for payment

Transfers

Request

Request

Request

Request