Acknowledge orchestration notification

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

Notifications

Operations

ODL flags configuration

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/ripplenet/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/ripplenet/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/ripplenet/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/ripplenet/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/ripplenet/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/ripplenet/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/ripplenet/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/ripplenet/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/ripplenet/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/ripplenet/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/ripplenet/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/ripplenet/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

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

Notifications

ODL flags configuration

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

Sender segregated account configuration

Transfers

schema

activity

Orchestration Template

diagnostics

payment

Get application info

Request

Request

Request

Request

Request