RippleNet Server API (4.0.0)

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

Check out the best practices and tutorials.

Authentication

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

API environments

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

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

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

Get audits

Gets an audit trail of user actions and configuration changes (to accounts, fees, and rates) on a RippleNet instance.

SecurityBearer
Request
query Parameters
page
integer
Default: 0

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.

size
integer [ 1 .. 100 ]
Default: 10

Number of payments to return per page.

before
string

Filters for audit events where the range_field value is before this specified time stamp (not inclusive). You can also specify after to create a time range between after and before. If before is specified, range_field must also be specified.

after
string

Filters for audit events where the range_field value is after this specified time stamp (not inclusive). You can also specify before to create a time range between after and before. If after is specified, range_field must also be specified.

range_field
string

Filters payments before/after/between created and modified timestamps (CREATED_AT, MODIFIED_AT). For example, if you specify range_field=CREATED_AT, you would specify a timestamp (in the 24-character ISO 8601 YYYY-MM-DDTHH:mm:ss.sssZ format used in payment objects) as the value for before and/or after to fetch audit events before, after, or between the specified time range(s) (not inclusive). If range_field is specified, before and/or after must also be specified.

actor
string

Filters for audit events based upon actor.

action
string

Filters for audit events based upon action.

level
string

Filters for audit events based upon audit level.

Enum: "INFO" "WARN" "ERROR"
domain
string

Filters for audit events based upon audit domain.

Enum: "USER_MANAGEMENT" "CONFIG_MANAGEMENT" "OTHER"
Responses
200

Successful response

400

Bad request.

get/audit
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "actor": "super_user_client",
      • "action": "KEY_UPDATE",
      • "eventId": "3d5d0831-762c-4e0c-980c-635b38fd9caf",
      • "message": "Added public key class PublicKeyRecord {\n    publicKey: MCowBQYDK2VwAyEAb8Q2YzrbTIwrUn7u5Q6hJimp7jBFHx500MfDM4XVNJ0=\n    keyIntent: SIGNING_PUBLIC_KEY\n    keyType: ED_25519\n    keyVersion: 1\n    expiryDateTime: 2089-09-23T17:27:50.331Z\n} for RippleNet address rn.us.ny.new_york",
      • "metadata": "{\"ip\":\"0:0:0:0:0:0:0:1\",\"uri\":\"/internal/key_service/addresses/rn.us.ny.new_york/keys\"}",
      • "domain": "CONFIG_MANAGEMENT",
      • "level": "INFO",
      • "timeStamp": "2019-09-30T22:55:41.365000Z"
      }
    ]
}
Get event trail for payment
Gets an audit trail of a payment's state changes on a local RippleNet instance.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Unique identifier of a payment.


 
Responses 
200
Payment state change event trail.


400
Bad request.


get/audit/payment/{id}
Request samples 
Response samples 
application/json
[
  • {
    • "featureName": "payment",
    • "eventDetail": "Updated Payment to state PREPARED",
    • "entityId": "d485f100-2af7-4e48-9ab1-3c7e28775691",
    • "messageAction": "STATE_CHANGE",
    • "createdAt": "2019-10-01T18:24:28.040000Z",
    • "messageSender": "default",
    • "messageType": "SETTLEMENT_PREPARE"
    }
]
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





Get balances
Get balances for local and remote accounts owned by a RippleNet address.


SecurityBearer 
Responses 
200
Successfully returned balances.


400
Bad request.


get/monitor/balances
Request samples 
Response samples 
application/json
{
  • "local_balance": [
    • {
      • "institution": "rn.us.ca.san_francisco",
      • "institution_address": "rn.us.ca.san_francisco",
      • "currency_balances": [
        • {
          • "currency": "USD",
          • "aggregate_balance": 0,
          • "account_balances": [
            • {
              • "account_name": "trans_usd_sf",
              • "balance": -909,
              • "owner": "rn.us.ca.san_francisco",
              • "currency": "USD",
              • "minimum_allowed_balance": -1500000,
              • "maximum_allowed_balance": 1000000,
              • "low_liquidity_threshold": 1000,
              • "owner_min_allowed_balance": 0,
              • "owner_max_allowed_balance": 1000000
              }
            ]
          }
        ],
      • "pool_account_balances": [
        • {
          • "pool_account_name": "string",
          • "balance": 0,
          • "owner": "string",
          • "currency": "string",
          • "linked_accounts": [
            • "string"
            ]
          }
        ]
      }
    ],
  • "remote_balances": [
    • {
      • "institution": "rn.us.ca.san_francisco",
      • "institution_address": "rn.us.ca.san_francisco",
      • "currency_balances": [
        • {
          • "currency": "USD",
          • "aggregate_balance": 0,
          • "account_balances": [
            • {
              • "account_name": "trans_usd_sf",
              • "balance": -909,
              • "owner": "rn.us.ca.san_francisco",
              • "currency": "USD",
              • "minimum_allowed_balance": -1500000,
              • "maximum_allowed_balance": 1000000,
              • "low_liquidity_threshold": 1000,
              • "owner_min_allowed_balance": 0,
              • "owner_max_allowed_balance": 1000000
              }
            ]
          }
        ],
      • "pool_account_balances": [
        • {
          • "pool_account_name": "string",
          • "balance": 0,
          • "owner": "string",
          • "currency": "string",
          • "linked_accounts": [
            • "string"
            ]
          }
        ]
      }
    ],
  • "errors": [
    • "string"
    ]
}
Get ledger balances
Get balances for ledger owned by a RippleNet address.


SecurityBearer 
Responses 
200
Successfully returned balances.


400
Bad request.


get/monitor/ledger/balances
Request samples 
Response samples 
application/json
{
  • "local_balance": [
    • {
      • "institution": "rn.us.ca.san_francisco",
      • "institution_address": "rn.us.ca.san_francisco",
      • "currency_balances": [
        • {
          • "currency": "USD",
          • "aggregate_balance": 0,
          • "account_balances": [
            • {
              • "account_name": "trans_usd_sf",
              • "balance": -909,
              • "owner": "rn.us.ca.san_francisco",
              • "currency": "USD",
              • "minimum_allowed_balance": -1500000,
              • "maximum_allowed_balance": 1000000,
              • "low_liquidity_threshold": 1000,
              • "owner_min_allowed_balance": 0,
              • "owner_max_allowed_balance": 1000000
              }
            ]
          }
        ],
      • "pool_account_balances": [
        • {
          • "pool_account_name": "string",
          • "balance": 0,
          • "owner": "string",
          • "currency": "string",
          • "linked_accounts": [
            • "string"
            ]
          }
        ]
      }
    ],
  • "remote_balances": [
    • {
      • "institution": "rn.us.ca.san_francisco",
      • "institution_address": "rn.us.ca.san_francisco",
      • "currency_balances": [
        • {
          • "currency": "USD",
          • "aggregate_balance": 0,
          • "account_balances": [
            • {
              • "account_name": "trans_usd_sf",
              • "balance": -909,
              • "owner": "rn.us.ca.san_francisco",
              • "currency": "USD",
              • "minimum_allowed_balance": -1500000,
              • "maximum_allowed_balance": 1000000,
              • "low_liquidity_threshold": 1000,
              • "owner_min_allowed_balance": 0,
              • "owner_max_allowed_balance": 1000000
              }
            ]
          }
        ],
      • "pool_account_balances": [
        • {
          • "pool_account_name": "string",
          • "balance": 0,
          • "owner": "string",
          • "currency": "string",
          • "linked_accounts": [
            • "string"
            ]
          }
        ]
      }
    ],
  • "errors": [
    • "string"
    ]
}
Get statement
Gets a statement for an account that lists payments and transfers that impacted the account's balance during a specified date-time range.


SecurityBearer 
Request 
path Parameters
account_name_with_address
required
string
The RippleNet account name and address that you want to return a statement for. Use the format accountname@ripplenetaddress. For example, san_francisco@rn.us.ca.san_francisco.


 
query Parameters
start-date
required
string
The lower bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC. For example, 2018-08-06T23:13:55.997Z.


 
end-date
required
string
The upper bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC For example, 2018-08-06T23:15:13.218Z.


 
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  10
Number of payment and transfer objects to return per page, with a limit of 100 per page.


For example, a query with "size": "100" results in "totalPages": "43" when the query result is "totalElements": "4290".


 
Responses 
200
Successfully returns an account statement.


400
Bad request.


404
Peer or Account not found.


get/statement/{account_name_with_address}
Request samples 
Response samples 
application/json
{
  • "account_name": "trans_usd_sf",
  • "start_datetime": "2018-08-06T23:13:55.997Z",
  • "end_datetime": "2020-08-06T23:13:55.997Z",
  • "generated_at": "2019-10-01T21:58:23.621Z",
  • "currency": "USD",
  • "owner": "rn.us.ca.san_francisco",
  • "opening_balance": 0,
  • "closing_balance": -909,
  • "transactions": {
    • "content": [
      • {
        • "transaction_id": "9eca588f-e89d-4629-82fa-da9c4646310f",
        • "transaction_type": "PAYMENT",
        • "transaction_state": "COMPLETED",
        • "balance_change": -15,
        • "balance_result": -909,
        • "created_at": "2019-10-01T21:28:28.354Z",
        • "end_to_end_id": "91ecb6bd-4dd8-4b53-a900-72b79f3064e4",
        • "internal_id": "8afd8e99-4ad4-4f4e-9bb7-018ad8c3a89c",
        • "venue_id": "nz7RpAujYgnQtjEM",
        • "transaction_hash": "DB0AFC09E0A94FC1D11F8CBABA48A184E27094F8DD32FCBC46F316E98011E2A6",
        • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
        • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
        • "balance_change_created_at": "2019-10-01T21:28:28.354Z",
        • "sender_address": "rn.us.ca.san_francisco",
        • "receiver_address": "rn.mx.mexico"
        }
      ],
    • "total_elements": 1,
    • "sort": "string",
    • "first": true,
    • "last": true,
    • "number": 0,
    • "numberOfElements": 1,
    • "size": 10,
    • "totalPages": 1
    }
}
Get statement by external account ID
Gets a statement for an account that lists payments and transfers that impacted the account's balance during a specified date-time range.


SecurityBearer 
Request 
path Parameters
external_account_id
required
string
The external account ID associated with the account.


 
query Parameters
start-date
required
string
The lower bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC. For example, 2018-08-06T23:13:55.997Z.


 
end-date
required
string
The upper bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC. For example, 2018-08-06T23:15:13.218Z.


 
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  10
Number of payment and transfer objects to return per page.


 
Responses 
200
Successfully returns an account statement.


400
Bad request.


404
Peer or Account not found.


get/statement/external_account_id/{external_account_id}
Request samples 
Response samples 
application/json
{
  • "account_name": "trans_usd_sf",
  • "start_datetime": "2018-08-06T23:13:55.997Z",
  • "end_datetime": "2020-08-06T23:13:55.997Z",
  • "generated_at": "2019-10-01T21:58:23.621Z",
  • "currency": "USD",
  • "owner": "rn.us.ca.san_francisco",
  • "opening_balance": 0,
  • "closing_balance": -909,
  • "transactions": {
    • "content": [
      • {
        • "transaction_id": "9eca588f-e89d-4629-82fa-da9c4646310f",
        • "transaction_type": "PAYMENT",
        • "transaction_state": "COMPLETED",
        • "balance_change": -15,
        • "balance_result": -909,
        • "created_at": "2019-10-01T21:28:28.354Z",
        • "end_to_end_id": "91ecb6bd-4dd8-4b53-a900-72b79f3064e4",
        • "internal_id": "8afd8e99-4ad4-4f4e-9bb7-018ad8c3a89c",
        • "venue_id": "nz7RpAujYgnQtjEM",
        • "transaction_hash": "DB0AFC09E0A94FC1D11F8CBABA48A184E27094F8DD32FCBC46F316E98011E2A6",
        • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
        • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
        • "balance_change_created_at": "2019-10-01T21:28:28.354Z",
        • "sender_address": "rn.us.ca.san_francisco",
        • "receiver_address": "rn.mx.mexico"
        }
      ],
    • "total_elements": 1,
    • "sort": "string",
    • "first": true,
    • "last": true,
    • "number": 0,
    • "numberOfElements": 1,
    • "size": 10,
    • "totalPages": 1
    }
}
Get ledger account statementDeprecated
Get statement for a specified Ledger account.


Note: This operation is deprecated. Use the Reports API to view your statements.


SecurityBearer 
Request 
path Parameters
account_name_with_address
required
string
The RippleNet account name and address that you want to return a statement for. Use the format accountname@ripplenetaddress. For example, san_francisco@rn.us.ca.san_francisco.


 
query Parameters
start-date
required
string
The lower bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC. For example, 2018-08-06T23:13:55.997Z.


 
end-date
required
string
The upper bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC For example, 2018-08-06T23:15:13.218Z.


 
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  10
Number of payment and transfer objects to return per page.


 
Responses 
200
Successfully returned statement for a specified ledger account.


400
Bad request.


404
Peer or Account not found.


get/statement/ledger/{account_name_with_address}
Request samples 
Response samples 
application/json
{
  • "account_name": "trans_usd_sf",
  • "start_datetime": "2018-08-06T23:13:55.997Z",
  • "end_datetime": "2020-08-06T23:13:55.997Z",
  • "generated_at": "2019-10-01T21:58:23.621Z",
  • "currency": "USD",
  • "owner": "rn.us.ca.san_francisco",
  • "opening_balance": 0,
  • "closing_balance": -909,
  • "transactions": {
    • "content": [
      • {
        • "transaction_id": "9eca588f-e89d-4629-82fa-da9c4646310f",
        • "transaction_type": "PAYMENT",
        • "transaction_state": "COMPLETED",
        • "balance_change": -15,
        • "balance_result": -909,
        • "created_at": "2019-10-01T21:28:28.354Z",
        • "end_to_end_id": "91ecb6bd-4dd8-4b53-a900-72b79f3064e4",
        • "internal_id": "8afd8e99-4ad4-4f4e-9bb7-018ad8c3a89c",
        • "venue_id": "nz7RpAujYgnQtjEM",
        • "transaction_hash": "DB0AFC09E0A94FC1D11F8CBABA48A184E27094F8DD32FCBC46F316E98011E2A6",
        • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
        • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
        • "balance_change_created_at": "2019-10-01T21:28:28.354Z",
        • "sender_address": "rn.us.ca.san_francisco",
        • "receiver_address": "rn.mx.mexico"
        }
      ],
    • "total_elements": 1,
    • "sort": "string",
    • "first": true,
    • "last": true,
    • "number": 0,
    • "numberOfElements": 1,
    • "size": 10,
    • "totalPages": 1
    }
}
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.





Get account lookup by status
Get Account Lookup entities by status and other filters. Status defaults to REQUESTED.


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  10
Number of objects to return per page


 
account_lookup_status
Array of strings (AccountLookupStatus) 
 Default:  ["REQUESTED"]
Account Lookup status


Items Enum: "REQUESTED" "PROCESSED" "FAILED" "EXPIRED"  
start-date
string
The lower bound of the date-time range you want to return account lookup for, as an ISO-8601 timestamp in UTC. For example, 2018-08-06T23:13:55.997Z.


 
end-date
string
The upper bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC For example, 2018-08-06T23:15:13.218Z.


 
sort_field
string
 Default:  "LAST_MODIFIED_DATE"
Attribute for how to sort the results


 Enum: "CREATED_DATE" "LAST_MODIFIED_DATE"  
sort_direction
string
 Default:  "ASC"
Direction of sorted results.


 Enum: "ASC" "DESC"  
Responses 
200
Successfully returned response for Account Lookup


400
Bad request problem


404
Account Lookup Not Found


500
Server Error - No valid network path to receiver. Account Lookup is not supported by a participant in the network path.


get/account_lookups
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "account_lookup_id": "efc26a87-de06-4aef-8217-4566df3c9f14",
      • "account_lookup_status": "REQUESTED",
      • "first_name": "string",
      • "middle_name": "string",
      • "last_name": "string",
      • "org_name": "string",
      • "country_code": "string",
      • "account_currency": "string",
      • "account_id": "string",
      • "account_id_type": "AIIN",
      • "result_code": "string",
      • "result_status": "PASS",
      • "result_description": "string",
      • "redacted_first_name": "string",
      • "redacted_middle_name": "string",
      • "redacted_last_name": "string",
      • "redacted_org_name": "string",
      • "redacted_country_code": "string",
      • "redacted_account_id": "string",
      • "redacted_account_id_type": "AIIN",
      • "redacted_account_currency": "string",
      • "clearing_system_code": "string",
      • "branch_code": "string"
      }
    ]
}
Initiate account lookup
Creates an Account Lookup request to validate a beneficiary's account details before sending a payment. Account lookups are not part of the payment flow and can be made at any time in the payment process.


SecurityBearer 
Request 
Request Body schema: application/json
required
account_currency
string
The 3 character currency code for the account as per ISO-4217 standards


 
clearing_system_code
string  <= 50 characters 
Clearing system code


 
destination_address
required
string
RippleNet address of the receiver.


 
first_name
string  <= 40 characters 
First name of the beneficiary.


 
middle_name
string  <= 40 characters 
Middle name of the beneficiary.


 
last_name
string  <= 40 characters 
Last name of the beneficiary.


 
org_name
string  <= 140 characters 
Name of the organization.


 
country_code
required
string  <= 2 characters 
Country of the beneficiary. Alpha-2 Code format per ISO 3166-1.


 
account_id
required
string  <= 40 characters 
Identifier for the Account, e.g account number.


 
account_id_type
required
string
Account ID type. Possible values are


    

  • AIIN - (default) Account Issue Identification Number
    • 

  • BBAN - Basic Bank Account Number
    • 

  • CARD - PAN of the card identifying the account
    • 

  • CUID - CHIPS Universal Identifier
    • 

  • UPIC - Universal Payment Identification Code
    • 

  • EMail - Email Address
    • 

  • MSISDN - Mobile Subscriber Integrated Service Digital Network (i.e., phone number)
    • 

  • DMST - Domestic
    • 

  • Other - Other identifier (e.g., PayID)
    • 



 Enum: "AIIN" "BBAN" "CARD" "CUID" "UPIC" "EMAIL" "MSISDN" "DMST" "OTHER"  
Responses 
200
Successfully returned Account Lookup response.


400
Bad Request Problem.


500
Server Error - No valid network path to receiver. Account Lookup is not supported by a participant in the network path.


post/account_lookups/request
Request samples 
application/json
{
  • "account_currency": "string",
  • "clearing_system_code": "string",
  • "destination_address": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "org_name": "string",
  • "country_code": "st",
  • "account_id": "string",
  • "account_id_type": "AIIN"
}
Response samples 
application/json
{
  • "account_lookup_id": "efc26a87-de06-4aef-8217-4566df3c9f14",
  • "account_lookup_status": "REQUESTED",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "org_name": "string",
  • "country_code": "string",
  • "account_currency": "string",
  • "account_id": "string",
  • "account_id_type": "AIIN",
  • "result_code": "string",
  • "result_status": "PASS",
  • "result_description": "string",
  • "redacted_first_name": "string",
  • "redacted_middle_name": "string",
  • "redacted_last_name": "string",
  • "redacted_org_name": "string",
  • "redacted_country_code": "string",
  • "redacted_account_id": "string",
  • "redacted_account_id_type": "AIIN",
  • "redacted_account_currency": "string",
  • "clearing_system_code": "string",
  • "branch_code": "string"
}
Complete account lookup
Posts an Account Lookup response to validate a beneficiary's account details before payment.


SecurityBearer 
Request 
Request Body schema: application/json
required
account_lookup_id
required
string <uuid> 
UUID that links Account Lookup request and response.


 
result_code
required
string^RNCB\d{4}
Result code of the Account Lookup response. Possible values are


    

  • RNCB0000 - Pass- Name and Identifier are correct and linked
    • 

  • RNCB0001 - Fail- Name and Identifier not found
    • 

  • RNCB0002 - Fail- Name and Identifier do not match
    • 



 
result_status
required
string
Result status of Account Lookup response


 Enum: "PASS" "FAIL"  
result_description
required
string
Result description of Account Lookup response


 
redacted_first_name
string  <= 40 characters 
First name of the beneficiary.


 
redacted_middle_name
string  <= 40 characters 
Middle name of the beneficiary.


 
redacted_last_name
string  <= 40 characters 
Last name of the beneficiary.


 
redacted_org_name
string  <= 140 characters 
Name of the organization.


 
redacted_country_code
string
Country of the beneficiary. Alpha-2 Code format per ISO 3166-1.


 
redacted_account_id
string  <= 40 characters 
Identifier for the Account, e.g account number.


 
redacted_account_id_type
string
Account ID type, redacted by the receiver. Possible values are


    

  • AIIN - (default) Account Issue Identification Number
    • 

  • BBAN - Basic Bank Account Number
    • 

  • CARD - PAN of the card identifying the account
    • 

  • CUID - CHIPS Universal Identifier
    • 

  • UPIC - Universal Payment Identification Code
    • 

  • EMail - Email Address
    • 

  • MSISDN - Mobile Subscriber Integrated Service Digital Network (i.e., phone number)
    • 

  • DMST - Domestic
    • 

  • Other - Other identifier (e.g., PayID)
    • 



 Enum: "AIIN" "BBAN" "CARD" "CUID" "UPIC" "EMAIL" "MSISDN" "DMST" "OTHER"  
redacted_clearing_system_code
string
Clearing system code


 
redacted_branch_code
string
The Branch code (e.g., routing code) that the receiver has on their system.


 
redacted_account_currency
string
The 3 character currency code for the account as per ISO-4217 standards


 
Responses 
200
Successfully returns acknowledgement for Account Lookup response.


400
Bad request problem


404
Account Lookup Not Found


500
Server Error - No valid network path to receiver. Account Lookup is not supported by a participant in the network path.


post/account_lookups/response
Request samples 
application/json
{
  • "account_lookup_id": "efc26a87-de06-4aef-8217-4566df3c9f14",
  • "result_code": "string",
  • "result_status": "PASS",
  • "result_description": "string",
  • "redacted_first_name": "string",
  • "redacted_middle_name": "string",
  • "redacted_last_name": "string",
  • "redacted_org_name": "string",
  • "redacted_country_code": "string",
  • "redacted_account_id": "string",
  • "redacted_account_id_type": "AIIN",
  • "redacted_clearing_system_code": "string",
  • "redacted_branch_code": "string",
  • "redacted_account_currency": "string"
}
Response samples 
application/json
{
  • "account_lookup_id": "efc26a87-de06-4aef-8217-4566df3c9f14",
  • "account_lookup_status": "REQUESTED",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "org_name": "string",
  • "country_code": "string",
  • "account_currency": "string",
  • "account_id": "string",
  • "account_id_type": "AIIN",
  • "result_code": "string",
  • "result_status": "PASS",
  • "result_description": "string",
  • "redacted_first_name": "string",
  • "redacted_middle_name": "string",
  • "redacted_last_name": "string",
  • "redacted_org_name": "string",
  • "redacted_country_code": "string",
  • "redacted_account_id": "string",
  • "redacted_account_id_type": "AIIN",
  • "redacted_account_currency": "string",
  • "clearing_system_code": "string",
  • "branch_code": "string"
}
Get account lookup by ID
Gets an Account Lookup entity for its account_lookup_id value.


SecurityBearer 
Request 
path Parameters
account_lookup_id
required
string <uuid> 
AccountLookupId


 
Responses 
200
Successfully returned Account Lookup response.


400
Bad request problem


404
Account Lookup Not Found


500
Server Error - No valid network path to receiver. Account Lookup is not supported by a participant in the network path.


get/account_lookups/{account_lookup_id}
Request samples 
Response samples 
application/json
{
  • "account_lookup_id": "efc26a87-de06-4aef-8217-4566df3c9f14",
  • "account_lookup_status": "REQUESTED",
  • "first_name": "string",
  • "middle_name": "string",
  • "last_name": "string",
  • "org_name": "string",
  • "country_code": "string",
  • "account_currency": "string",
  • "account_id": "string",
  • "account_id_type": "AIIN",
  • "result_code": "string",
  • "result_status": "PASS",
  • "result_description": "string",
  • "redacted_first_name": "string",
  • "redacted_middle_name": "string",
  • "redacted_last_name": "string",
  • "redacted_org_name": "string",
  • "redacted_country_code": "string",
  • "redacted_account_id": "string",
  • "redacted_account_id_type": "AIIN",
  • "redacted_account_currency": "string",
  • "clearing_system_code": "string",
  • "branch_code": "string"
}
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.





Check health
Gets the health status of the xCurrent server.


SecurityBearer 
Responses 
200
Successful response.


400
Bad request.


get/health
Request samples 
Response samples 
application/json
{
  • "healthy": true,
  • "services": [
    • {
      • "service": "database",
      • "healthy": true,
      • "detail": "Message queue unreachable."
      }
    ],
  • "detail": "Failed to perform health check"
}
Check heartbeat
Gets the health status of the xCurrent server's peers. This request requires authorization. The timeout for this operation is 5 seconds.


SecurityBearer 
Responses 
200
Successful response.


400
Bad request.


get/heartbeat
Request samples 
Response samples 
application/json
{
  • "time_checked": "2019-10-01",
  • "xcurrent_node": "rn.us.ny.new_york",
  • "ripplenet_node": "rn.us.ny.new_york",
  • "peer_heartbeat_results": {
    • "property1": "HEALTHY",
    • "property2": "HEALTHY"
    },
  • "errors": [
    • "string"
    ]
}
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.





Get exchange transfers
Gets all exchange transfers.


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  20
Number of objects to return per page.


 
Responses 
200
Successfully retrieved exchange transfers.


400
Bad request.


get/exchange_transfers
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "exchange_transfer_id": "e3b20ba4-28ed-4752-990d-e67887bb331e",
      • "state": "EXECUTED",
      • "type": "INDICATIVE",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "source_amount": 1,
      • "destination_amount": 355,
      • "source_currency": "USD",
      • "destination_currency": "GBP",
      • "fx_transfer_rate": {
        • "rate": 0.89,
        • "base_currency": "USD",
        • "counter_currency": "GBP",
        • "rate_type": "BUY"
        },
      • "end_to_end_id": "string",
      • "internal_id": "string",
      • "user_info": [
        • {
          • "node_address": "rn.us.ny.new_york",
          • "state": "EXECUTED",
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z"
          }
        ]
      }
    ]
}
Execute exchange transfer
Execute an exchange transfer to move funds from one of your accounts in one currency (USD, for example) to another one of your accounts in another currency (EUR, for example) at an exchange rate set by your peer who maintains both of your accounts on their ledger. An exchange transfer enables you to fund a foreign currency account from your domestic currency account in bulk.


Before you make this request, you may want to use the Quote Exchange Transfer request to see a quote for the exchange transfer you want to make.


SecurityBearer 
Request 
Request Body schema: application/json
required
sender_address
required
string
RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.


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


 
amount
required
number  >= 0 
Amount transferred, expressed in the curency of the account indicated by the amount_type value.


 
amount_type
required
string
Amount type used for the exchange transfer.
To indicate that the amount is expressed in the currency of the account provided by the sender_address value, set to SENDER_AMOUNT.
 
To indicate that the amount is expressed in the currency of the account provided by the receiver_address value, set to RECEIVER_AMOUNT.


 Enum: "SENDER_AMOUNT" "RECEIVER_AMOUNT"  
end_to_end_id
string  <= 128 characters 
ID set by the sender that is persisted on all fiat node instances that participated in the transfer.


 
internal_id
string  <= 128 characters 
Internal ID that the sender can optionally specify. Only visible to the sender. Only the sending fiat node instance stores this ID.


 
user_info
object
Provide one or more arbitrary key/value pairs.


 
Responses 
200
Successfully executed exchange transfer.


400
Bad request.


post/exchange_transfers/execute
Request samples 
application/json
{
  • "sender_address": "alias_usd_lon@rn.eur.uk.london",
  • "receiver_address": "conct_gbp_lon@rn.eur.uk.london",
  • "amount": 100,
  • "amount_type": "SENDER_AMOUNT",
  • "end_to_end_id": 378910,
  • "internal_id": 1987,
  • "user_info": { }
}
Response samples 
application/json
{
  • "exchange_transfer_id": "e3b20ba4-28ed-4752-990d-e67887bb331e",
  • "state": "EXECUTED",
  • "type": "INDICATIVE",
  • "sender_address": "sf@rn.us.ca.san_francisco",
  • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
  • "source_amount": 1,
  • "destination_amount": 355,
  • "source_currency": "USD",
  • "destination_currency": "GBP",
  • "fx_transfer_rate": {
    • "rate": 0.89,
    • "base_currency": "USD",
    • "counter_currency": "GBP",
    • "rate_type": "BUY"
    },
  • "end_to_end_id": "string",
  • "internal_id": "string",
  • "user_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "state": "EXECUTED",
      • "json": { },
      • "created_at": "2019-08-24T14:15:22Z"
      }
    ]
}
Get exchange transfer quote
Requests a quote for an exchange transfer.


SecurityBearer 
Request 
Request Body schema: application/json
required
sender_address
required
string
RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.


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


 
amount
required
number  >= 0 
Amount transferred, expressed in the curency of the account indicated by the amount_type value.


 
amount_type
required
string
Amount type of the exchange transfer.
To indicate that the amount is expressed in the currency of the account provided by the sender_address value, set to SENDER_AMOUNT.
 
To indicate that the amount is expressed in the currency of the account provided by the receiver_address value, set to RECEIVER_AMOUNT.


 Enum: "SENDER_AMOUNT" "RECEIVER_AMOUNT"  
Responses 
200
Successfully quoted exchange transfer.


400
Bad request.


post/exchange_transfers/quote
Request samples 
application/json
{
  • "sender_address": "alias_usd_lon@rn.eur.uk.london",
  • "receiver_address": "conct_gbp_lon@rn.eur.uk.london",
  • "amount": 100,
  • "amount_type": "SENDER_AMOUNT"
}
Response samples 
application/json
{
  • "type": "INDICATIVE",
  • "sender_address": "alias_usd_lon@rn.eur.uk.london",
  • "receiver_address": "conct_gbp_lon@rn.eur.uk.london",
  • "source_amount": 100,
  • "destination_amount": 89,
  • "source_currency": "USD",
  • "destination_currency": "GBP",
  • "fx_transfer_rate": {
    • "rate": 0.89,
    • "base_currency": "USD",
    • "counter_currency": "GBP",
    • "rate_type": "BUY"
    }
}
Complete exchange transfer
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.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Unique identifier of the exchange transfer to complete.


 
Responses 
200
Successfully completed exchange transfer.


404
Exchange transfer not found.


post/exchange_transfers/{id}/complete
Request samples 
Response samples 
application/json
{
  • "exchange_transfer_id": "e3b20ba4-28ed-4752-990d-e67887bb331e",
  • "state": "EXECUTED",
  • "type": "INDICATIVE",
  • "sender_address": "sf@rn.us.ca.san_francisco",
  • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
  • "source_amount": 1,
  • "destination_amount": 355,
  • "source_currency": "USD",
  • "destination_currency": "GBP",
  • "fx_transfer_rate": {
    • "rate": 0.89,
    • "base_currency": "USD",
    • "counter_currency": "GBP",
    • "rate_type": "BUY"
    },
  • "end_to_end_id": "string",
  • "internal_id": "string",
  • "user_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "state": "EXECUTED",
      • "json": { },
      • "created_at": "2019-08-24T14:15:22Z"
      }
    ]
}
Get exchange transfer by ID
Gets an exchange transfer by ID.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Unique identifier of the exchange transfer you want to retrieve.


 
Responses 
200
Successfully retrieved exchange transfer.


404
Exchange transfer not found.


get/exchange_transfers/{id}
Request samples 
Response samples 
application/json
{
  • "exchange_transfer_id": "e3b20ba4-28ed-4752-990d-e67887bb331e",
  • "state": "EXECUTED",
  • "type": "INDICATIVE",
  • "sender_address": "sf@rn.us.ca.san_francisco",
  • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
  • "source_amount": 1,
  • "destination_amount": 355,
  • "source_currency": "USD",
  • "destination_currency": "GBP",
  • "fx_transfer_rate": {
    • "rate": 0.89,
    • "base_currency": "USD",
    • "counter_currency": "GBP",
    • "rate_type": "BUY"
    },
  • "end_to_end_id": "string",
  • "internal_id": "string",
  • "user_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "state": "EXECUTED",
      • "json": { },
      • "created_at": "2019-08-24T14:15:22Z"
      }
    ]
}
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.





Get fees
Gets a list of fees.


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
Number of pages returned. Returns one page of results when set to 0.


 
size
integer
 Default:  10
Number of objects returned per page.


 
Responses 
200
Successfully returns list of fees.


400
Bad request.


get/config/fees
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "value": 2,
      • "currency_code": "USD",
      • "role_type": "SENDING",
      • "payment_type": "REGULAR",
      • "node_type": "INITIAL",
      • "fee_type": "FLAT_RATE",
      • "partner_name": "rn.us.ca.san_francisco",
      • "account_name": "conct_usd_sf",
      • "upper_limit": 1000,
      • "lower_limit": 0,
      • "feeId": "7740f31c-ca03-4414-b491-b285aef71eb1",
      • "payout_method": "LOCAL_RAILS",
      • "fee_category": "BENEFICIARY_BANK_CHARGE",
      • "fee_description": "string"
      }
    ]
}
Create fee
Creates a fee.


SecurityBearer 
Request 
Request Body schema: application/json
required
value
required
number
Value of the fee to apply.


Set the value of this parameter according to the fee type you are using:






fee_type
Corresponding value to use





PERCENTAGE
value must be >0 and <100.




FLAT_RATE
value can be negative.





Note: The final amount of the fee is applied either as a percentage or a flat rate depending on the value you specify for the fee_type parameter.


 
currency_code
required
string
Currency the fee is applied in. Ripple recommends using ISO-4217 currency codes, although no formal constraint is enforced.


 
role_type
required
string
Role of the party to which the fee applies.


 Enum Value Description
SENDING
Charge the originator of the payment.


RECEIVING
Charge the beneficiary of the payment.


INSTITUTION_SENDING
Charge the financial institution sending the payment.


INSTITUTION_RECEIVING
Charge the financial institution receiving the payment.


 
payment_type
required
string
Type of payment to which the fee applies.


 Enum Value Description
REGULAR
Apply the fee to a regular payment.


RETURN
Apply the fee to a return payment.


 
node_type
required
string
Fiat instance to which the fee applies.


 Enum Value Description
INITIAL
Apply the fee to the first fiat instance in the payment chain.


INTERMEDIATE
Apply the fee to each fiat instance in the payment chain that is not the first or last.


TERMINAL
Apply the fee to the last fiat instance in the payment chain.


 
fee_type
required
string
Type of fee to apply. This is used with fee value to calculate the fee.


 Enum Value Description
PERCENTAGE
Apply the fee value as a percentage.


FLAT_RATE
Apply the fee value as a flat rate.


 
partner_name
string
Owner of the account involved in the payment, in RippleNet Address format. For example, rn.us.ca.san_francisco.


 
account_name
string
Account to apply the fee to. Specify the account name. For example, conct_usd_sf. If specified, you must also specify a partner_name value.


 
upper_limit
number
Maximum amount for the range of a slab-based fee. If specified, you must also specify a lower_limit value.


 
lower_limit
number
Minimum amount for the range of a slab-based fee. If specified, you must also specify an upper_limit value.


 
payout_method
string
The payout method by which the receiving institution delivers the funds to the end customer.


 
fee_category
string
 Default:  "NONE"
Category that describes the purpose of the fee.


 Enum Value Description
NONE
None


OVERSEAS_DELIVERY_CHARGES
Overseas delivery charges.


BENEFICIARY_BANK_CHARGE
Charge from beneficiary bank.


PROCESSING_HANDLING_CHARGE
Processing and handling charge.


LOCAL_GOVERNMENT_CHARGE
Local government charge.


OTHER
Other charges.


 
fee_description
string
Optional free-form description for the fee.


 
Responses 
200
Successfully created fee.


400
Bad Request.


post/config/fees
Request samples 
application/json
{
  • "value": 0.025,
  • "currency_code": "USD",
  • "role_type": "SENDING",
  • "payment_type": "REGULAR",
  • "node_type": "INITIAL",
  • "fee_type": "FLAT_RATE",
  • "partner_name": "rn.us.ca.san_francisco",
  • "account_name": "conct_usd_sf",
  • "upper_limit": 1000,
  • "lower_limit": 0,
  • "payout_method": "LOCAL_RAILS",
  • "fee_category": "BENEFICIARY_BANK_CHARGE",
  • "fee_description": "string"
}
Response samples 
application/json
{
  • "value": 2,
  • "currency_code": "USD",
  • "role_type": "SENDING",
  • "payment_type": "REGULAR",
  • "node_type": "INITIAL",
  • "fee_type": "FLAT_RATE",
  • "partner_name": "rn.us.ca.san_francisco",
  • "account_name": "conct_usd_sf",
  • "upper_limit": 1000,
  • "lower_limit": 0,
  • "feeId": "7740f31c-ca03-4414-b491-b285aef71eb1",
  • "payout_method": "LOCAL_RAILS",
  • "fee_category": "BENEFICIARY_BANK_CHARGE",
  • "fee_description": "string"
}
Get fee by ID
Gets a fee by ID.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Provide the feeId of the fee you want to retrieve.


 
Responses 
200
Successfully retrieved fee.


404
Fee not found.


get/config/fees/{id}
Request samples 
Response samples 
application/json
{
  • "value": 2,
  • "currency_code": "USD",
  • "role_type": "SENDING",
  • "payment_type": "REGULAR",
  • "node_type": "INITIAL",
  • "fee_type": "FLAT_RATE",
  • "partner_name": "rn.us.ca.san_francisco",
  • "account_name": "conct_usd_sf",
  • "upper_limit": 1000,
  • "lower_limit": 0,
  • "feeId": "7740f31c-ca03-4414-b491-b285aef71eb1",
  • "payout_method": "LOCAL_RAILS",
  • "fee_category": "BENEFICIARY_BANK_CHARGE",
  • "fee_description": "string"
}
Update fee
Updates an existing fee.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Provide the feeId of the fee you want to update.


 
Request Body schema: application/json
required
value
required
number
Value of the fee to apply.


Set the value of this parameter according to the fee type you are using:






fee_type
Corresponding value to use





PERCENTAGE
value must be >0 and <100.




FLAT_RATE
value can be negative.





Note: The final amount of the fee is applied either as a percentage or a flat rate depending on the value you specify for the fee_type parameter.


 
currency_code
required
string
Currency the fee is applied in. Ripple recommends using ISO-4217 currency codes, although no formal constraint is enforced.


 
role_type
required
string
Role of the party to which the fee applies.


 Enum Value Description
SENDING
Charge the originator of the payment.


RECEIVING
Charge the beneficiary of the payment.


INSTITUTION_SENDING
Charge the financial institution sending the payment.


INSTITUTION_RECEIVING
Charge the financial institution receiving the payment.


 
payment_type
required
string
Type of payment to which the fee applies.


 Enum Value Description
REGULAR
Apply the fee to a regular payment.


RETURN
Apply the fee to a return payment.


 
node_type
required
string
Fiat instance to which the fee applies.


 Enum Value Description
INITIAL
Apply the fee to the first fiat instance in the payment chain.


INTERMEDIATE
Apply the fee to each fiat instance in the payment chain that is not the first or last.


TERMINAL
Apply the fee to the last fiat instance in the payment chain.


 
fee_type
required
string
Type of fee to apply. This is used with fee value to calculate the fee.


 Enum Value Description
PERCENTAGE
Apply the fee value as a percentage.


FLAT_RATE
Apply the fee value as a flat rate.


 
partner_name
string
Owner of the account involved in the payment, in RippleNet Address format. For example, rn.us.ca.san_francisco.


 
account_name
string
Account to apply the fee to. Specify the account name. For example, conct_usd_sf. If specified, you must also specify a partner_name value.


 
upper_limit
number
Maximum amount for the range of a slab-based fee. If specified, you must also specify a lower_limit value.


 
lower_limit
number
Minimum amount for the range of a slab-based fee. If specified, you must also specify an upper_limit value.


 
payout_method
string
The payout method by which the receiving institution delivers the funds to the end customer.


 
fee_category
string
 Default:  "NONE"
Category that describes the purpose of the fee.


 Enum Value Description
NONE
None


OVERSEAS_DELIVERY_CHARGES
Overseas delivery charges.


BENEFICIARY_BANK_CHARGE
Charge from beneficiary bank.


PROCESSING_HANDLING_CHARGE
Processing and handling charge.


LOCAL_GOVERNMENT_CHARGE
Local government charge.


OTHER
Other charges.


 
fee_description
string
Optional free-form description for the fee.


 
Responses 
200
Successfully updated fee.


400
Bad Request.


put/config/fees/{id}
Request samples 
application/json
{
  • "value": 0.025,
  • "currency_code": "USD",
  • "role_type": "SENDING",
  • "payment_type": "REGULAR",
  • "node_type": "INITIAL",
  • "fee_type": "FLAT_RATE",
  • "partner_name": "rn.us.ca.san_francisco",
  • "account_name": "conct_usd_sf",
  • "upper_limit": 1000,
  • "lower_limit": 0,
  • "payout_method": "LOCAL_RAILS",
  • "fee_category": "BENEFICIARY_BANK_CHARGE",
  • "fee_description": "string"
}
Response samples 
application/json
{
  • "value": 2,
  • "currency_code": "USD",
  • "role_type": "SENDING",
  • "payment_type": "REGULAR",
  • "node_type": "INITIAL",
  • "fee_type": "FLAT_RATE",
  • "partner_name": "rn.us.ca.san_francisco",
  • "account_name": "conct_usd_sf",
  • "upper_limit": 1000,
  • "lower_limit": 0,
  • "feeId": "7740f31c-ca03-4414-b491-b285aef71eb1",
  • "payout_method": "LOCAL_RAILS",
  • "fee_category": "BENEFICIARY_BANK_CHARGE",
  • "fee_description": "string"
}
Delete fee
Deletes a fee. Once deleted, a fee cannot be accessed.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Provide the feeId of the fee you want to delete.


 
Responses 
200
Successfully deleted fee.


400
Bad request.


delete/config/fees/{id}
Request samples 
Response samples 
application/json
{}
Non-orchestration payments
Get payments
Retrieves all payments in an instance of xCurrent that meet the criteria defined by the query parameters. You can use the query parameters to filter payments. The default parameters are sort_field : MODIFIED_AT , sort_direction : DESC , page : 0 , size : 10


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  10
Number of payments to return per page.


 
sending_host
string
Optional parameter for filtering with sendingHost value.


 
receiving_host
string
Optional parameter for filtering with receivingHost value.


 
sending_account
string
Optional parameter for filtering with sendingAccount value.


 
receiving_account
string
Optional parameter for filtering with receivingAccount value.


 
sending_currency
string
Optional parameter for filtering with sendingCurrency value.


 
receiving_currency
string
Optional parameter for filtering with receivingCurrency value.


 
payment_id
string <uuid> 
 Deprecated 
Optional parameter for filtering with paymentId value. This parameter is deprecated. Please use payment_ids instead


 
payment_type
string
Filters for payments based on the type of payment. Valid types are REGULAR, RETURN.


 
internal_id
string
Optional parameter for filtering with internalId.


 
sender_end_to_end_id
string
Optional parameter for filtering with senderEndToEndId.


 
connector_role
string
Filters for payments based on the role of the responding connector. Valid roles are SENDING, INTERMEDIARY, RECEIVING, and INTERNAL. The INTERNAL role is meant for payments between RippleNet Cloud and RippleNet where the sender and receiver accounts are on the same RippleNet instance. Use role with state to find payments waiting on action from you as the sending or receiving (or internal) connector.


 
state
string
Deprecated, should use states parameter. Returns payments in the specified state. The following options are valid: ACCEPTED, COMPLETED, EXECUTED, FAILED, LOCKED, LOCK_DECLINED, PREPARED, RETURNED, and SETTLEMENT_DECLINED


 
states
Array of strings
Returns payments in the specified states. The following options are valid: ACCEPTED, COMPLETED, EXECUTED, FAILED, LOCKED, LOCK_DECLINED, PREPARED, RETURNED, and SETTLEMENT_DECLINED


 
before
string
Filters for payments where the payments range_field column value is before this specified time stamp (not inclusive). You can also specify after to create a time range between after and before. If before is specified, range_field must also be specified.


 
after
string
Filters for payments where the payments range_field column value is after this specified time stamp (not inclusive). You can also specify before to create a time range between after and before. If after is specified, range_field must also be specified.


 
range_field
string
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: CREATED_AT, MODIFIED_AT, ACCEPTED_AT, LOCKED_AT, EXECUTED_AT, COMPLETED_AT, RETURNED_AT and EXPIRES_AT. For example, if you specify range_field=MODIFIED_AT, you would specify a time stamp (in the 24 character ISO 8601 YYYY-MM-DDTHH:mm:ss.sssZ format used in payment objects) as the value for before and/or after to fetch payments before, after, or between the specified time range(s) (not inclusive). If range_field is specified, before and/or after must also be specified.


 
amount_range_field
string
Designates the column name of the payments database table that is used for filtering payments greater/less/between amounts. For example, if you specify amount_range_field=SENDING_AMOUNT, you would specify an amount as the value for greater and/or less to fetch payments greater, less, or between the specified amounts (inclusive). If amount_range_field is specified, minAmount and/or maxAmount must also be specified.


 Enum: "SENDING_AMOUNT" "RECEIVING_AMOUNT"  
min_amount
number  >= 0 
Optional parameter for filtering with min sending/receiving amount.


 
max_amount
number  >= 0 
Optional parameter for filtering with max sending/receiving amount.


 
with_labels
Array of strings
Returns payments with the specified labels. 
If you apply with_labels with multiple labels, the response returns payments with at least one of the specified labels.
 
For example, the query, 
 
?with_labels=string1,string2
 
returns payments with either "string1" OR "string2".


 
without_labels
Array of strings
Returns payments that do not have any of the specified labels. 
If you apply without_labels with multiple labels, the response returns payments that do not have any of the specified labels.
 
For example, the query,
 
?without_labels=string3,string4
 
returns payments that are not labeled with either "string3" OR "string4".
 
If you apply both with_labels and without_labels parameters, the response returns payments that have at least one of the specified with_labels strings but omits payments that also have any of the the without_labels strings. 
 
For example, the query, 
 
?with_labels=string1&without_labels=string3
 
returns payments with "string1" but not payments with "string3".


 
sort_field
string
 Default:  "MODIFIED_AT"
Sorts results according to the specified field. Valid options are PAYMENT_ID, EXPIRES_AT, MODIFIED_AT and CREATED_AT.


 
sort_direction
string
 Default:  "DESC"
Sorts result according to the specified direction. Valid options are ASC, DESC.


 
load_additional_details
boolean
 Default:  true
This parameter can be used to exclude additional info being returned for each payment object. Additional info which will be excluded if the flag set to false include user_info, ripplenet_info, execution_results and internal_info.labels


 
payment_ids
Array of strings <uuid> 
List of paymentIds to search for


 
Responses 
200
Successful response


400
Bad request.


get/payments
Request samples 
Response samples 
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
      • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
      • "payment_state": "COMPLETED",
      • "modified_at": "2019-10-01T18:25:47.347Z",
      • "contract": {
        • "sender_end_to_end_id": "string",
        • "created_at": "2019-10-01T18:18:13.665Z",
        • "expires_at": "2019-10-01T18:55:22.824Z",
        • "quote": {
          • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
          • "created_at": "2020-01-29T20:59:44.925Z",
          • "expires_at": "2020-01-29T21:29:44.925Z",
          • "type": "SENDER_AMOUNT",
          • "price_guarantee": "FIRM",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "amount": "1",
          • "currency_code": "USD",
          • "currency_code_filter": "EUR",
          • "service_type": "string",
          • "quote_elements": [
            • {
              • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
              • "quote_element_type": "EXCHANGE",
              • "quote_element_order": "1",
              • "sender_address": "sf@rn.us.ca.san_francisco",
              • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
              • "sending_amount": 1,
              • "receiving_amount": 355,
              • "sending_fee": 0,
              • "receiving_fee": 0,
              • "sending_currency_code": "USD",
              • "receiving_currency_code": "GBP",
              • "fx_rate": {
                • "rate": null,
                • "base_currency_code": null,
                • "counter_currency_code": null,
                • "type": null
                },
              • "transfer_currency_code": "string"
              }
            ],
          • "liquidity_warning": "string",
          • "payment_method": "LOCAL_RAILS",
          • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
          • "payout_method_info": {
            • "payout_method_name": "Cash Payout",
            • "payout_method_category": "BOOK_TRANSFER",
            • "description": "local rails",
            • "estimated_time_to_credit": "3 days"
            }
          },
        • "fee_info": {
          • "nodes": {
            • "property1": [
              • {
                • "fee_value": null,
                • "fee_currency": null,
                • "category": null,
                • "fee_description": null
                }
              ],
            • "property2": [
              • {
                • "fee_value": null,
                • "fee_currency": null,
                • "category": null,
                • "fee_description": null
                }
              ]
            },
          • "total_fees": [
            • {
              • "total_fee": 0,
              • "fee_currency": "string"
              }
            ]
          }
        },
      • "ripplenet_info": [
        • {
          • "node_address": "rn.us.ny.new_york",
          • "settlement_declined": [
            • {
              • "info": "L001",
              • "created_at": "2018-04-06T20:33:35Z"
              }
            ]
          }
        ],
      • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
      • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
      • "validator": "rn.us.ca.san_francisco",
      • "payment_type": "REGULAR",
      • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
      • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
      • "execution_results": [
        • {
          • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
          • "execution_timestamp": "2019-10-01T18:24:29.867Z",
          • "execution_result_type": "TRANSFER",
          • "execution_result_order": 1,
          • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
          • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
          • "sending_amount": 498,
          • "receiving_amount": 498,
          • "sending_fee": 2,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string",
          • "intermediary_delta": 0.2,
          • "incentive_type": "firm",
          • "incentive_value": 0.2,
          • "transaction_hash": 5.5467794184785867e+76,
          • "venue_id": "nz7RpAujYgnQtjEM",
          • "fiat_adjusted_value": 0.02,
          • "odl_payment_id": "string"
          }
        ],
      • "liquidation_execution_results": [
        • {
          • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
          • "execution_timestamp": "2019-10-01T18:24:29.867Z",
          • "execution_result_type": "TRANSFER",
          • "execution_result_order": 1,
          • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
          • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
          • "sending_amount": 498,
          • "receiving_amount": 498,
          • "sending_fee": 2,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string",
          • "intermediary_delta": 0.2,
          • "incentive_type": "firm",
          • "incentive_value": 0.2,
          • "transaction_hash": 5.5467794184785867e+76,
          • "venue_id": "nz7RpAujYgnQtjEM",
          • "fiat_adjusted_value": 0.02,
          • "odl_payment_id": "string"
          }
        ],
      • "liquidation_details": {
        • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        • "status": "string",
        • "failure_reason": "string",
        • "failure_count": 0
        },
      • "push_forward_execution_results": [
        • {
          • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
          • "execution_timestamp": "2019-10-01T18:24:29.867Z",
          • "execution_result_type": "TRANSFER",
          • "execution_result_order": 1,
          • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
          • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
          • "sending_amount": 498,
          • "receiving_amount": 498,
          • "sending_fee": 2,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string",
          • "intermediary_delta": 0.2,
          • "incentive_type": "firm",
          • "incentive_value": 0.2,
          • "transaction_hash": 5.5467794184785867e+76,
          • "venue_id": "nz7RpAujYgnQtjEM",
          • "fiat_adjusted_value": 0.02,
          • "odl_payment_id": "string"
          }
        ],
      • "accepted_at": "2019-10-01T18:25:47.347Z",
      • "locked_at": "2019-10-01T18:25:47.347Z",
      • "executed_at": "2019-10-01T18:25:47.347Z",
      • "completed_at": "2019-10-01T18:25:47.347Z",
      • "returned_at": "2019-10-01T18:25:47.347Z",
      • "internal_info": {
        • "connector_role": "RECEIVING",
        • "labels": [
          • {
            • "label": "string"
            }
          ],
        • "internal_id": "string"
        },
      • "user_info": [
        • {
          • "node_address": "rn.us.ca.san_francisco",
          • "accepted": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "locked": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "lock_declined": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "retry_accept": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "retry_settlement": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "settlement": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "settlement_declined": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "failed": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "executed": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "completed": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "forwarded": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "returned": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ]
          }
        ]
      }
    ]
}
Get payment by payment ID
Gets a payment by ID.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of the payment you want to retrieve.


 
Responses 
200
Successfully retrieved payment.


400
Bad request.


404
Payment not found.


get/payments/{payment_id}
Request samples 
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "locked_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "returned_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    • "connector_role": "RECEIVING",
    • "labels": [
      • {
        • "label": "string"
        }
      ],
    • "internal_id": "string"
    },
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Lock payment
Locks a payment. The beneficiary and all intermediary institutions agree to proceed with the payment by making successful Lock Payment requests. When the payment is still in a partially LOCKED state, the beneficiary and all intermediary institutions who have not locked, can reject lock payment or fail payment.


Once fully LOCKED, the originating institution can either fail payment or Settle payment. If the originating institution sends a Settle payment request, one of three things will happen:


    

  • Successful payments move to the PREPARED state.
    • 

  • Payments with insufficient liquidity automatically move into state SETTLEMENT_DECLINED, or
    • 

  • Payments that are not settled before the crypto_transaction_id expires move to the FAILED state.
    • 



Note: Currently, when making a Create quote to 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.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of the payment to lock.


 
Request Body schema: application/json
required
internal_id
string  <= 128 characters 
ID that intermediaries and the receiver can set when locking a payment. The ID is viewable only by the node that set it.


 
user_info
object
Provide one or more arbitrary key/value pairs. 
 
Caution: Ripple recommends that you always include this object, even when empty, to ensure that the RippleNet Payment Object includes the created_at timestamp, which records when the payment was locked. To add an empty object, include: {"user_info":[]}


 
Responses 
200
Successfully locked payment.


400
Bad request.


404
Payment not found.


post/payments/{payment_id}/lock
Request samples 
application/json
{
  • "internal_id": "string",
  • "user_info": { }
}
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "locked_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "returned_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    • "connector_role": "RECEIVING",
    • "labels": [
      • {
        • "label": "string"
        }
      ],
    • "internal_id": "string"
    },
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Reject lock payment
Rejects a payment from being locked.


This temporarily stops the payment and keeps it in a recoverable state so that user_info can be corrected. If the payment is incorrect for reasons outside of the user_info object, use Fail payment.


After a payment has been created by an Accept quote request, the beneficiary or an intermediary can choose to reject the payment, rather than Lock payment, with corrections to user_info in the reasons array. A rejected payment moves the payment state to LOCK_DECLINED from which it can be recovered by the originating institution with a Retry accept payment request.


If any one institution in the payment chain is configured to auto-fail, the payment automatically fails when the payment is rejected, moving to the FAILED state rather than the LOCK_DECLINED state.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of a payment to reject a lock request.


 
Request Body schema: application/json
required
reasons
required
object
Provide one or more arbitrary key/value pairs.


 
Responses 
200
Successfully rejected the request to lock a payment.


400
Bad request.


404
Payment not found.


post/payments/{payment_id}/reject
Request samples 
application/json
{
  • "reasons": {
    • "type": "RECEIVER_DATA_VALIDATION",
    • "code": "AC03",
    • "reason": "Creditor account number invalid or missing"
    }
}
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "locked_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "returned_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    • "connector_role": "RECEIVING",
    • "labels": [
      • {
        • "label": "string"
        }
      ],
    • "internal_id": "string"
    },
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Retry accept payment
Returns a rejected payment from the LOCK_DECLINED state to the ACCEPTED state. The payment sender must include repaired user_info in the request body.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of the payment to return to ACCEPTED state.


 
Request Body schema: application/json
required
user_info
object
Provide one or more arbitrary key/value pairs.


 
Responses 
200
Successfully resubmitted payment for locking.


400
Bad request.


404
Payment not found.


post/payments/{payment_id}/retry_accept
Request samples 
application/json
{
  • "user_info": {
    • "SF ACCEPTED": "Payment to NY",
    • "last_name": "Gonzalez",
    • "first_name": "Elle"
    }
}
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "locked_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "returned_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    • "connector_role": "RECEIVING",
    • "labels": [
      • {
        • "label": "string"
        }
      ],
    • "internal_id": "string"
    },
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Fail payment
Fails a payment. Fail payment is a deliberate action that permanently stops the payment and puts it into a non-recoverable state.


An institution rejects a payment to solicit changes to user_info; it fails a payment to stop it altogether. After a payment has been created by an Accept quote request, you can fail the payment if it is your institution's turn to take an action on the payment.


The originating institution can fail a payment in states LOCKED and LOCK_DECLINED. The beneficiary and intermediary institutions can fail a payment in the ACCEPTED state. Beneficiary institutions can also fail a payment in the EXECUTED state. The general use case for failing an executed payment is to Create quote to return payment to the originating institution.


Payments in states PREPARED and SETTLEMENT_DECLINED can fail automatically—PREPARED when the crypto-transaction expires and SETTLEMENT_DECLINED when the payment expires.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of the payment to fail.


 
Request Body schema: application/json
required
reasons
required
object
Provide one or more arbitrary key/value pairs.


 
Responses 
200
Successfully failed a payment.


400
Bad request.


404
Payment not found.


post/payments/{payment_id}/fail
Request samples 
application/json
{
  • "reasons": {
    • "type": "RECEIVER_DATA_VALIDATION",
    • "code": "AC03",
    • "reason": "Creditor account number invalid or missing"
    }
}
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "locked_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "returned_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    • "connector_role": "RECEIVING",
    • "labels": [
      • {
        • "label": "string"
        }
      ],
    • "internal_id": "string"
    },
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Settle payment
Executes a payment in the LOCKED state. Payment senders can also retry settling a payment in the SETTLEMENT_DECLINED state, after the error is corrected (and before the payment expires).
Settle payment sends a prepare payment transfer message, which travels to all participants in the payment. This sets the payment state to PREPARED, which means that funds have been transferred to the hold account on that xCurrent ledger.
 
The beneficiary institution then signs the execution_condition (creating a payload) and sends an execute payment transfer message, which travels to all participants in the payment). When the payment is fully executed, funds have been transferred from the hold account to the receiver account on all xCurrent ledgers and the payment state is set to EXECUTED.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of the payment to settle.


 
Request Body schema: application/json
user_info
object
Provide one or more arbitrary key/value pairs.


 
Responses 
200
Successfully prepared payment settlement. Execution is asynchronous.


400
Bad request.


404
Payment not found.


409
Concurrent request already in progress. Any 200 response result is unchanged.


post/payments/{payment_id}/settle
Request samples 
application/json
{
  • "user_info": { }
}
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "locked_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "returned_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    • "connector_role": "RECEIVING",
    • "labels": [
      • {
        • "label": "string"
        }
      ],
    • "internal_id": "string"
    },
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Finalize payment
Marks a payment with finalized sub-states that reflect what is happening to the payment while it is in the EXECUTED state. The receiving institution can make this request multiple times to provide a log of each subsequent sub-state until it is ready to make the Complete payment request.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of a payment for which to set a sub-state.


 
Request Body schema: application/json
required
sub_state
required
string  [ 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.


 
memo
required
string
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.


 
Responses 
200
Returns a payment with sub-states represented as labels.


400
Bad request.


404
Payment not found.


post/payments/{payment_id}/finalize
Request samples 
application/json
{
  • "sub_state": "FORWARDED",
  • "memo": "Heading to payout location"
}
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "locked_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "returned_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    • "connector_role": "RECEIVING",
    • "labels": [
      • {
        • "label": "string"
        }
      ],
    • "internal_id": "string"
    },
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Add payment sub state
Adds a sub-state to a payment that reflects what is happening to the payment while it is in the EXECUTED state. All nodes on the payment chain can make this request multiple times to provide a log of each subsequent sub-state until the receiver is ready to make the Complete payment request.
This operation is especially useful for completing cash payouts—sending institutions can add clarifying user information to a payment after it has been executed (and money has been moved). 


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of a payment for which to set a sub-state.


 
Request Body schema: application/json
required
sub_state
required
string  [ 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.


 
memo
required
string
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.


 
info
object
Provide one or more arbitrary key/value pairs.


 
Responses 
200
Returns a payment with sub-states represented as labels.


400
Bad request.


404
Payment not found.


post/payments/{payment_id}/sub_state
Request samples 
application/json
{
  • "sub_state": "AMENDED",
  • "memo": "Last name must be corrected",
  • "info": {
    • "last_name": "Gonzales"
    }
}
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "locked_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "returned_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    • "connector_role": "RECEIVING",
    • "labels": [
      • {
        • "label": "string"
        }
      ],
    • "internal_id": "string"
    },
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Complete payment
Marks a payment as complete by placing it in the COMPLETED state. Typically, the receiving institution makes this request when it has delivered payment funds to the final beneficiary on its internal systems outside of xCurrent.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of the payment to place in the COMPLETED state.


 
Request Body schema: application/json
required
user_info
object
Provide one or more arbitrary key/value pairs.


 
Responses 
200
Returns a completed payment.


400
Bad request.


404
Payment not found.


post/payments/{payment_id}/complete
Request samples 
application/json
{
  • "user_info": { }
}
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "locked_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "returned_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    • "connector_role": "RECEIVING",
    • "labels": [
      • {
        • "label": "string"
        }
      ],
    • "internal_id": "string"
    },
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Add payment labels
Adds a list of labels to the payment. To retrieve payments by label, see Get payments.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of the payment you want to label.


 
query Parameters
label
required
Array of strings
Text of the label you want to add to the payment.


 
Responses 
200
Successfully added one or more labels to the payment.


400
Bad request.


404
Payment not found.


put/payments/{payment_id}/labels
Request samples 
Response samples 
application/json
{}
Delete payment labels
Deletes an existing label from a payment. The label you provide is deleted from the labels array in the Payment object.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of the payment from which to delete a label.


 
query Parameters
label
required
Array of strings
Text of the label you want to delete from the payment.


 
Responses 
200
Successfully deleted label from payment.


400
Bad request.


404
Labels to be deleted not found on the payment ID.


delete/payments/{payment_id}/labels
Request samples 
Response samples 
application/json
{}
Get payment node status
Senders can query for the RippleNet instances (in a given payment chain) that have payments in the LOCKED state. This information is only stored on the sender's RippleNet instance.


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of the payment for which to get states on each node participating in the payment.


 
Responses 
200
Successfully retrieved payment states on each node participating in the payment.


400
Bad request.


404
Payment not found.


get/payments/{payment_id}/node-status
Request samples 
Response samples 
application/json
[
  • {
    • "paymentId": "efdf213c-9f64-43f7-80ab-15e7b4d139ae",
    • "paymentState": "LOCKED",
    • "nodeAddress": "rn.eur.uk.london",
    • "pathOrder": 3
    }
]
Get filtered payment by payment ID
Returns a sanitized payment with sensitive content filtered from the user_info object. 
Filtering user_info is customizable in rnn.properties. Content that is denylisted by default:
 
/Cdtr, /CdtrAcct, /Dbtr, /DbtrAcct, /InitgPty, /InstForCdtrAgt, /Purp, /RgltryRptg, /RltdRmtInf, /RmtInf, /UltmtCdtr, /UltmtDbtr, /outbound_instructions/beneficiary_info


SecurityBearer 
Request 
path Parameters
payment_id
required
string <uuid> 
Unique identifier of the filtered payment you want to retrieve.


 
Responses 
200
Successfully retrieved filtered payment.


400
Bad request.


404
Payment not found.


get/payments/filtered/{payment_id}
Request samples 
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Create quote to return payment
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.


SecurityBearer 
Request 
Request Body schema: application/json
required
original_payment_id
required
string <uuid> 
ID of the original payment to be returned.


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


For more information about return reasons, see Specific Data Messaging in the RippleNet Rulebook.


 
return_amount_type
string
 Default:  "TOTAL_RECEIVED"
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.


 Enum: "TOTAL_RECEIVED" "TOTAL_RECEIVED_MINUS_FEES"  
custom_fee
number
Custom fee charged and collected by the sending account. Setting this field overrides all applicable fees configured on the sender's RippleNet instance.


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


 
force_path_finding_and_liquidity_path_finding
boolean
 Default:  false
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.


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


 
Responses 
200
Successfully returned a collection of quotes to return a payment.


400
Bad request.


404
Payment not found.


500
Server Error - an internal error occured while making Return Quote calls.


post/quote_collections/return
Request samples 
application/json
{
  • "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"
}
Response samples 
application/json
{
  • "quote_collection_id": "4711728c-cd35-49ec-96a5-72732b4333ec",
  • "quotes": [
    • {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      }
    ],
  • "quote_errors": [
    • {
      • "failed_path": [
        • {
          • "source": "string",
          • "destination": "string",
          • "source_currency": "string",
          • "destination_currency": "string",
          • "account_liquidity_relationship_id": "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6",
          • "peer_liquidity_relationship_id": "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"
          }
        ],
      • "error_origin": "string",
      • "error_message": "string"
      }
    ]
}
Create quote to reverse payment
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.


SecurityBearer 
Request 
Request Body schema: application/json
required
original_payment_id
required
string <uuid> 
ID of the original payment to be reversed.


 
required
object (PaymentReversalReason) 
A structured object detailing reasons for a payment reversal.


 
Responses 
200
Successfully returned a collection of quotes to return a payment.


400
Original payment has previously been returned, reversed, or is in an invalid payment state for reversal.


404
Original payment was not found.


500
Reversals are disabled on this instance.


post/quote_collections/reversal
Request samples 
application/json
{
  • "original_payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "reversal_reason": {
    • "code": "RB001",
    • "description": "No account / Unable to locate account"
    }
}
Response samples 
application/json
{
  • "quote_collection_id": "4711728c-cd35-49ec-96a5-72732b4333ec",
  • "quotes": [
    • {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      }
    ],
  • "quote_errors": [
    • {
      • "failed_path": [
        • {
          • "source": "string",
          • "destination": "string",
          • "source_currency": "string",
          • "destination_currency": "string",
          • "account_liquidity_relationship_id": "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6",
          • "peer_liquidity_relationship_id": "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"
          }
        ],
      • "error_origin": "string",
      • "error_message": "string"
      }
    ]
}
Orchestration payments
Create orchestration payment
Creates an orchestration payment.


SecurityBearer 
Request 
Request Body schema: application/json
required
sender_end_to_end_id
required
string  [ 1 .. 64 ] characters ^[a-zA-Z0-9@_,:\s-]*$
Unique ID that the sender can specify.


Persisted on all instances that participate in the payment.


 
internal_id
string  [ 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_template
string  [ 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_address
required
string  [ 1 .. 256 ] characters ^([\.a-zA-Z0-9_~-]+@)?(rn|dev|test|uat)([.][a...
RippleNet account name and address of the sender.


Format: accountname@ripplenetaddress


Example: new_york@rn.us.ny.new_york


 
receiving_address
required
string  [ 1 .. 256 ] characters ^([\.a-zA-Z0-9_~-]+@)?(rn|dev|test|uat)([.][a...
RippleNet account name and address of the receiver.


Format: accountname@ripplenetaddress


Example: new_york@rn.us.ny.new_york


 
amount
required
string  >= 1 
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





 
currency
required
string  = 3 characters 
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





 
quote_type
required
string
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


 
sender_or_receiver_currency
string  = 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


 
custom_fee
number
Custom fee for the sending account.


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


 
object (PaymentCustomRateRequest) 
Custom rate that the return payment quotes must use.


 
quote_route
Array 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


 
payment_method
string  [ 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_method
boolean
Enable this flag to generate quotes using payout methods configured by the receiver.


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


 
force_path_finding_and_liquidity_path_finding
boolean
 Default:  false
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.


 
payout_method_category
string
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


 
user_info
required
object
Provide one or more arbitrary key/value pairs.


 
sender_segregated_account
string
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


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


 
quote_filter_types
Array of strings
Filter on a type of quote.


Items Enum Value Description
LIQUIDITY_WARNINGS
Filter for liquidity warnings


QUOTE_ERRORS
Filter for quote errors


 
Responses 
201
Successfully created orchestration payment.


post/v4/orchestration/payment
Request samples 
application/json
{
  • "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"
    ]
}
Response samples 
application/json
{
  • "sender_end_to_end_id": "00310000015"
}
Get orchestration payments
Gets a list of orchestration payments.


SecurityBearer 
Request 
query Parameters
page
integer
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  10
Number of objects to return per page.


 
sort_field
string
 Default:  "MODIFIED_AT"
Attribute to sort the results on.






Enum:
Sort by





CREATED_AT
Created date-time




MODIFIED_AT
Modified date-time





 Enum: "CREATED_AT" "MODIFIED_AT"  
sort_direction
string
 Default:  "ASC"
Direction of sorted results based on sort_field.






Enum:
Description





ASC
Sort ascending




DESC
Sort descending





 Enum: "ASC" "DESC"  
unique_reference_number
string
Parameter for filtering with unique reference number.


 
orchestration_status
string
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_field
string
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.


 
before
string
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


 
after
string
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


 
Responses 
200
Successfully fetched all orchestration payments.


get/v4/orchestration/payment
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "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"
      }
    ]
}
Get orchestration payment
Gets orchestration payment by unique reference number.


SecurityBearer 
Request 
path Parameters
uniqueReferenceNumber
required
string <String>   [ 1 .. 64 ] characters ^[a-zA-Z0-9@_,:\s-]*$
Unique reference number of the orchestration payment to fetch.


 
Responses 
200
Successfully returned orchestration payment.


get/v4/orchestration/payment/{uniqueReferenceNumber}
Request samples 
Response samples 
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
Returns the orchestration payment with customer end-to-end ID.


SecurityBearer 
Request 
Request Body schema: application/json
required
sender_end_to_end_id
required
string  [ 1 .. 64 ] characters ^[a-zA-Z0-9@_,:\s-]*$
Unique ID that the sender can specify.


 
original_payment_id
required
string  [ 1 .. 64 ] characters ^[a-zA-Z0-9@_,:\s-]*$
Unique ID of the payment that should be returned.


 
return_reasons
object
Provide one or more arbitrary key/value pairs.


 
return_amount_type
string
 Default:  "TOTAL_RECEIVED"
Amount type of the return payment.


 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_fee
number
Custom fee charged and collected by the sending account.


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


 
object (PaymentCustomRateRequest) 
Custom rate that the return payment quotes must use.


 
force_path_finding_and_liquidity_path_finding
boolean
 Default:  false
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.


 
user_info
object
Provide one or more arbitrary key/value pairs.


 
Responses 
201
Successfully returned orchestration payment.


post/v4/orchestration/payment/return
Request samples 
application/json
{
  • "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": { }
}
Response samples 
application/json
{
  • "sender_end_to_end_id": "00310000015"
}
Accept orchestration payment
Accepts the orchestration payment with customer end-to-end ID and Quote ID.


SecurityBearer 
Request 
Request Body schema: application/json
required
sender_end_to_end_id
required
string  [ 1 .. 64 ] characters ^[a-zA-Z0-9@_,:\s-]*$
Unique ID that the sender can specify.


Persisted on all instances that participate in the payment.


 
internal_id
string  [ 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_id
required
string <uuid> 
ID of the quote to accept and continue as a payment.


 
orchestration_template
string  [ 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_info
required
object
provide one or more arbitrary key/value pairs.


 
Responses 
201
Successfully accepted orchestration payment.


post/v4/orchestration/payment/accept
Request samples 
application/json
{
  • "sender_end_to_end_id": "string",
  • "internal_id": "string",
  • "quote_id": "5492648d-2132-4e70-9ded-2fc86f22b321",
  • "orchestration_template": "string",
  • "user_info": { }
}
Response samples 
application/json
{
  • "sender_end_to_end_id": "00310000015"
}
Reverse orchestration payment
Reverses the orchestration payment with customer end-to-end ID.


SecurityBearer 
Request 
Request Body schema: application/json
required
sender_end_to_end_id
required
string  [ 1 .. 64 ] characters ^[a-zA-Z0-9@_,:\s-]*$
Unique ID that the sender can specify.


 
original_payment_id
required
string  [ 1 .. 64 ] characters ^[a-zA-Z0-9@_,:\s-]*$
Unique ID of the payment that should be reversed.


 
required
object (PaymentReversalReasonRos) 
A structured object detailing reasons for a payment reversal.


 
Responses 
201
Successfully returned orchestration payment.


post/v4/orchestration/payment/reversal
Request samples 
application/json
{
  • "sender_end_to_end_id": "string",
  • "original_payment_id": "string",
  • "reversal_reason": {
    • "code": "RB001",
    • "description": "No account / Unable to locate account"
    }
}
Response samples 
application/json
{
  • "sender_end_to_end_id": "00310000015"
}
Get orchestration notifications by status
Gets a list of orchestration payment notifications with a given status.


SecurityBearer 
Request 
query Parameters
status
required
string
The 'status' of the notifications to retrieve.


 Enum: "NEW" "SENT"  
size
integer  [ 1 .. 100 ] 
 Default:  10
Number of objects to return per page.


 
delay_time
integer
 Default:  30
Delay time in minutes to retrieve the SENT notifications.


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


 
before
string
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


 
after
string
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


 
Responses 
200
Successfully fetched orchestration payment notifications list.


get/v4/orchestration/payment/notification
Request samples 
Response samples 
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
Gets orchestration payment notifications with a given unique reference number.


SecurityBearer 
Request 
path Parameters
uniqueReferenceNumber
required
string <string> 
The sender_end_to_end_id of the orchestration payment notification in case of sender and payment_id in case of receiver.


 
Responses 
200
Successfully fetched orchestration payment notifications.


get/v4/orchestration/payment/notification/urn/{uniqueReferenceNumber}
Request samples 
Response samples 
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
Gets a given orchestration payment notification by UUID.


SecurityBearer 
Request 
path Parameters
uuid
required
string <uuid> 
The UUID of the orchestration payment notification.


 
Responses 
200
Successfully fetched orchestration paymnet notification.


get/v4/orchestration/payment/notification/{uuid}
Request samples 
Response samples 
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
Acknowledges an orchestration payment notification with a specified UUID.


SecurityBearer 
Request 
path Parameters
uuid
required
string <uuid> 
The UUID of the orchestration payment notification.


 
Responses 
200
Successfully updated orchestration payment notification status.


put/v4/orchestration/payment/notification/{uuid}/ack
Request samples 
Response samples 
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
Acknowledges multiple orchestration payment notifications using a list of UUIDs.


SecurityBearer 
Request 
Request Body schema: application/json
required
uuids
Array of strings <uuid>   non-empty 
List of orchestration payment notification UUIDs.


 
Responses 
200
Successfully acknowledged orchestration payment notifications.


put/v4/orchestration/payment/notification/ack
Request samples 
application/json
{
  • "uuids": [
    • "328b3e50-7983-46d5-94a0-ef004d78db1d"
    ]
}
Response samples 
application/json
{
  • "notification_ack_list": [
    • {
      • "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"
      }
    ],
  • "invalid_uuid_list": [
    • "328b3e50-7983-46d5-94a0-ef004d78db1d"
    ]
}
Post action to orchestration payment
Posts action into the Orchestration service.


SecurityBearer 
Request 
Request Body schema: application/json
required
unique_reference_number
required
string  [ 1 .. 64 ] characters ^[a-zA-Z0-9@_,:\s-]*$
Set to the unique reference number associated with the payment.


 
status
required
string (ActivityStatus) 
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


 
notification_type
required
string  [ 1 .. 128 ] characters ^[a-zA-Z0-9_:]*$
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

Use with output.sub_state to provide additional information.		





 
object (ActivityOutput) 
Use this object when notification_type is PARTNER_SUBSTATE.


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


 
Array of objects (ActivityError) 
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.


 
Responses 
201
Successfully posted action.


post/v4/orchestration/payment/action
Request samples 
application/json
{
  • "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"
}
Response samples 
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.





Get payment expiry by ID
Gets the time to live (ttl) of a payment expiry in seconds.


SecurityBearer 
Request 
path Parameters
payment_expiry_id
required
string <uuid> 
The ID of the payment expiry you want returned.


 
Responses 
200
Successfully returned a payment expiry.


400
Bad request.


get/config/payments/payment_expiries/{payment_expiry_id}
Request samples 
Response samples 
application/json
{
  • "payment_ttl": 5900,
  • "sending_partner": "rn.us.ca.san_francisco",
  • "receiving_partner": "rn.us.tx.austin",
  • "currency": "USD",
  • "expiry_id": "4711728c-cd35-49ec-96a5-72732b4333ec"
}
Update payment expiry
Updates the time to live (ttl) of a payment expiry in seconds.


SecurityBearer 
Request 
path Parameters
payment_expiry_id
required
string <uuid> 
Provide the payment_expiry_id of the payment expiry you want to update.


 
Request Body schema: application/json
required
payment_ttl
number
Payment expiration window, or time to live (ttl), in seconds. To calculate the payment expiration date, xCurrent adds this value to the payment creation timestamp.


 
sending_partner
string
RippleNet address of the sender, in the format ripplenetaddress. For example, rn.us.sf.san_francisco.


 
receiving_partner
string
RippleNet address of the receiver, in the format ripplenetaddress. For example, rn.us.ny.new_york.


 
currency
string
currency of the exchange rate.


 
Responses 
200
Successfully updated payment expiry.


400
Bad request.


put/config/payments/payment_expiries/{payment_expiry_id}
Request samples 
application/json
{
  • "payment_ttl": 5900,
  • "sending_partner": "rn.us.ca.san_francisco",
  • "receiving_partner": "rn.us.tx.austin",
  • "currency": "USD"
}
Response samples 
application/json
{
  • "payment_ttl": 5900,
  • "sending_partner": "rn.us.ca.san_francisco",
  • "receiving_partner": "rn.us.tx.austin",
  • "currency": "USD",
  • "expiry_id": "4711728c-cd35-49ec-96a5-72732b4333ec"
}
Delete payment expiry
Deletes a payment expiry.


SecurityBearer 
Request 
path Parameters
payment_expiry_id
required
string <uuid> 
Provide the payment_expiry_id of the payment expiry you want to delete.


 
Responses 
200
Successfully deleted payment expiry.


400
Bad request.


delete/config/payments/payment_expiries/{payment_expiry_id}
Request samples 
Response samples 
application/json
{}
Get payment expiries
Returns all configured payment expiries.


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
Zero-based index of the page number of results.


 
size
integer
 Default:  10
Number of payments returned per page.


 
Responses 
200
Successful response


400
Bad request.


get/config/payments/payment_expiries
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "payment_ttl": 5900,
      • "sending_partner": "rn.us.ca.san_francisco",
      • "receiving_partner": "rn.us.tx.austin",
      • "currency": "USD",
      • "expiry_id": "4711728c-cd35-49ec-96a5-72732b4333ec"
      }
    ]
}
Create payment expiry
Creates a payment expiration window, or time to live (ttl), in seconds.


SecurityBearer 
Request 
Request Body schema: application/json
required
payment_ttl
number
Payment expiration window, or time to live (ttl), in seconds. To calculate the payment expiration date, xCurrent adds this value to the payment creation timestamp.


 
sending_partner
string
RippleNet address of the sender, in the format ripplenetaddress. For example, rn.us.sf.san_francisco.


 
receiving_partner
string
RippleNet address of the receiver, in the format ripplenetaddress. For example, rn.us.ny.new_york.


 
currency
string
currency of the exchange rate.


 
Responses 
200
Successfully created the payment expiration window.


400
Bad request.


post/config/payments/payment_expiries
Request samples 
application/json
{
  • "payment_ttl": 5900,
  • "sending_partner": "rn.us.ca.san_francisco",
  • "receiving_partner": "rn.us.tx.austin",
  • "currency": "USD"
}
Response samples 
application/json
{
  • "payment_ttl": 5900,
  • "sending_partner": "rn.us.ca.san_francisco",
  • "receiving_partner": "rn.us.tx.austin",
  • "currency": "USD",
  • "expiry_id": "4711728c-cd35-49ec-96a5-72732b4333ec"
}
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.





Create payout method
Creates a payout method (for example, LOCAL_RAILS). 
The Payout Method API lets receivers create and manage payout methods. Senders can generate quotes based on these receiver payout methods by enabling the flag enable_quote_per_payout_method in the body of the [Create quote collection] request. 
Caution: The existing quote parameter is named payment_method while elsewhere it is payout_method.
Note: On-Demand Liquidity (ODL) receivers should set payment_method to the outlet_id or the string none (not an empty value) to keep funds at the destination exchange when paying out to a local rail.


SecurityBearer 
Request 
Request Body schema: application/json
required
payout_method
required
string
Unique string used in the quote to identify the payout method.


 
description
string
User defined description of a payout method.


 
is_default
boolean
Flag to set this payout method as the default payout method.


 
payout_method_category
string
Category of the payout method. Defaults to OTHER 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"  
object
The estimated time to credit the beneficiary using this payout method.


 
Responses 
200
Successfully created payout method.


400
Bad request.


post/config/payout_methods
Request samples 
application/json
{
  • "payout_method": "LOCAL_RAILS",
  • "description": "local rails",
  • "is_default": true,
  • "payout_method_category": "BOOK_TRANSFER",
  • "estimated_time_to_credit": {
    • "time_value": 5,
    • "time_unit": "SECONDS"
    }
}
Response samples 
application/json
{
  • "payout_method_id": "a6dbe002-ca7f-4ec7-89e4-f44a1971a0c0",
  • "payout_method": "LOCAL_RAILS",
  • "description": "local rails",
  • "is_default": true,
  • "payout_method_category": "BOOK_TRANSFER",
  • "estimated_time_to_credit": {
    • "time_value": 5,
    • "time_unit": "SECONDS"
    }
}
Get payout methods
Returns a list of payout methods created by a receiving partner.


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  10
Number of payments to return per page.


 
Responses 
200
400
Bad request.


get/config/payout_methods
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "payout_method_id": "a6dbe002-ca7f-4ec7-89e4-f44a1971a0c0",
      • "payout_method": "LOCAL_RAILS",
      • "description": "local rails",
      • "is_default": true,
      • "payout_method_category": "BOOK_TRANSFER",
      • "estimated_time_to_credit": {
        • "time_value": 5,
        • "time_unit": "SECONDS"
        }
      }
    ]
}
Get payout method by ID
Returns a payout method by its ID.


SecurityBearer 
Request 
path Parameters
payout_method_id
required
string <uuid> 
ID of the payout method you want to retrieve.


 
Responses 
200
Successfully returned Payout method


400
Bad request.


get/config/payout_methods/{payout_method_id}
Request samples 
Response samples 
application/json
{
  • "payout_method_id": "a6dbe002-ca7f-4ec7-89e4-f44a1971a0c0",
  • "payout_method": "LOCAL_RAILS",
  • "description": "local rails",
  • "is_default": true,
  • "payout_method_category": "BOOK_TRANSFER",
  • "estimated_time_to_credit": {
    • "time_value": 5,
    • "time_unit": "SECONDS"
    }
}
Update payout method
Updates a payout method.


SecurityBearer 
Request 
path Parameters
payout_method_id
required
string <uuid> 
ID of the payout method you want to retrieve.


 
Request Body schema: application/json
required
payout_method
required
string
Unique string used in the quote to identify the payout method.


 
description
string
User defined description of a payout method.


 
is_default
boolean
Flag to set this payout method as the default payout method.


 
payout_method_category
string
Category of the payout method. Defaults to OTHER 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"  
object
The estimated time to credit the beneficiary using this payout method.


 
Responses 
200
Successfully saved Payout method


400
Bad request.


put/config/payout_methods/{payout_method_id}
Request samples 
application/json
{
  • "payout_method": "LOCAL_RAILS",
  • "description": "local rails",
  • "is_default": true,
  • "payout_method_category": "BOOK_TRANSFER",
  • "estimated_time_to_credit": {
    • "time_value": 5,
    • "time_unit": "SECONDS"
    }
}
Response samples 
application/json
{
  • "payout_method_id": "a6dbe002-ca7f-4ec7-89e4-f44a1971a0c0",
  • "payout_method": "LOCAL_RAILS",
  • "description": "local rails",
  • "is_default": true,
  • "payout_method_category": "BOOK_TRANSFER",
  • "estimated_time_to_credit": {
    • "time_value": 5,
    • "time_unit": "SECONDS"
    }
}
Delete payout method
Deletes a payout method.


SecurityBearer 
Request 
path Parameters
payout_method_id
required
string <uuid> 
ID of the payout method you want to retrieve.


 
Responses 
200
Successfully deleted payout method.


400
Bad request.


delete/config/payout_methods/{payout_method_id}
Request samples 
Response samples 
application/json
{}
Get all categories
Returns all the payout method categories.


SecurityBearer 
Responses 
200
Successfully returned Payout method Categories


400
Bad request.


get/config/payout_methods/categories
Request samples 
Response samples 
application/json
[
  • "string"
]
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





Create platform
Creates a RippleNet platform, which represents a financial entity that holds accounts in the real world (e.g. Bank, Exchange or Wallet provider). This operation creates a database record for a platform account on a RippleNet node.


SecurityBearer 
Request 
Request Body schema: application/json
required
name
required
string
Name of the platform.


 
platform_type
required
string
The type of institution this platform represents (WALLET_PROVIDER, FIAT_INSTITUTION, or DIGITAL_EXCHANGE).


 Enum: "WALLET_PROVIDER" "FIAT_INSTITUTION" "DIGITAL_EXCHANGE"  
description
string  <= 512 characters 
A short description of the platform.


 
institution
required
string
Name of the institution this platform represents.


 
servicer_code
required
string
Akin to the routing number (US), Sort Code (UK), or IFSC code (India).


 
Responses 
200
Successfully created RippleNet platform.


400
Bad request.


post/config/platforms
Request samples 
application/json
{
  • "name": "string",
  • "platform_type": "WALLET_PROVIDER",
  • "description": "string",
  • "institution": "string",
  • "servicer_code": "string"
}
Response samples 
application/json
{
  • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
  • "name": "string",
  • "platform_type": "WALLET_PROVIDER",
  • "description": "string",
  • "institution": "string",
  • "servicer_code": "string"
}
Get all platforms
Returns a list of all active RippleNet platforms.


SecurityBearer 
Responses 
200
List of all active RippleNet platforms.


400
Bad request.


get/config/platforms
Request samples 
Response samples 
application/json
[
  • {
    • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
    • "name": "string",
    • "platform_type": "WALLET_PROVIDER",
    • "description": "string",
    • "institution": "string",
    • "servicer_code": "string"
    }
]
Get platform by platform ID
Get a RippleNet platform by its platform ID.


SecurityBearer 
Request 
path Parameters
platform_id
required
string <uuid> 
ID of the platform you want to retrieve.


 
Responses 
200
Returns a RippleNet platform for the given platform ID.


400
Bad request.


get/config/platforms/{platform_id}
Request samples 
Response samples 
application/json
{
  • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
  • "name": "string",
  • "platform_type": "WALLET_PROVIDER",
  • "description": "string",
  • "institution": "string",
  • "servicer_code": "string"
}
Update platform
Updates a RippleNet platform, which represents a financial entity that holds accounts in the real world (e.g. Bank, Exchange or Wallet provider). This operation creates a database record for a platform account on a RippleNet node.


SecurityBearer 
Request 
path Parameters
platform_id
required
string <uuid> 
ID of the platform you want to update.


 
Request Body schema: application/json
required
name
string
Name of the platform.


 
platform_type
string
The type of institution this platform represents (WALLET_PROVIDER, FIAT_INSTITUTION, or DIGITAL_EXCHANGE).


 Enum: "WALLET_PROVIDER" "FIAT_INSTITUTION" "DIGITAL_EXCHANGE"  
description
string  <= 512 characters 
A short description of the platform.


 
institution
string
Name of the institution this platform represents.


 
servicer_code
string
Akin to the routing number (US), Sort Code (UK), or IFSC code (India).


 
Responses 
200
Successfully updated RippleNet platform.


400
Bad request.


put/config/platforms/{platform_id}
Request samples 
application/json
{
  • "name": "string",
  • "platform_type": "WALLET_PROVIDER",
  • "description": "string",
  • "institution": "string",
  • "servicer_code": "string"
}
Response samples 
application/json
{
  • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
  • "name": "string",
  • "platform_type": "WALLET_PROVIDER",
  • "description": "string",
  • "institution": "string",
  • "servicer_code": "string"
}
Delete platform by platform ID
Deletes a RippleNet platform by its platform ID.


SecurityBearer 
Request 
path Parameters
platform_id
required
string <uuid> 
ID of the platform you want to delete.


 
Responses 
204
Deleted platform successfully.


400
Bad request.


delete/config/platforms/{platform_id}
Request samples 
Response samples 
application/json
{}
Create platform account
Creates a RippleNet platform account, which represents a real-world account owned by a financial entity (e.g. Bank, Exchange or Wallet provider). This operation creates a database record for a platform account on a RippleNet node.


SecurityBearer 
Request 
Request Body schema: application/json
required
name
required
string
Name of the platform account.


 
platform_id
required
string <uuid> 
The unique identifier for the RippleNet platform where this account is defined.


 
description
string  <= 512 characters 
A short description of the platform account.


 
external_account_id
required
string
Unique reference identifier for the real world account which is represented by this platform account.


 
currency
required
string  <= 3 characters 
The currency of the account. Ripple recommends using ISO-4217 currency codes.


 
Responses 
200
Successfully created RippleNet platform account.


400
Bad request.


post/config/platforms/accounts
Request samples 
application/json
{
  • "name": "string",
  • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
  • "description": "string",
  • "external_account_id": "string",
  • "currency": "str"
}
Response samples 
application/json
{
  • "platform_account_id": "8301de71-1ac1-4edb-8119-73ff911eb9ad",
  • "name": "string",
  • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
  • "description": "string",
  • "external_account_id": "string",
  • "currency": "string",
  • "balance": 0
}
Get platform accounts
Returns a paged list of all active RippleNet platform accounts.


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  10
Number of objects to return per page.


 
Responses 
200
Paged list of all active RippleNet platform accounts.


400
Bad request.


get/config/platforms/accounts
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "platform_account_id": "8301de71-1ac1-4edb-8119-73ff911eb9ad",
      • "name": "string",
      • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
      • "description": "string",
      • "external_account_id": "string",
      • "currency": "string",
      • "balance": 0
      }
    ]
}
Get platform account by platform account ID
Gets a RippleNet platform account by its platform account ID.


SecurityBearer 
Request 
path Parameters
platform_account_id
required
string <uuid> 
ID of the platform account you want to retrieve.


 
Responses 
200
Returns a RippleNet platform account for the given platform account ID.


400
Bad request.


get/config/platforms/accounts/{platform_account_id}
Request samples 
Response samples 
application/json
{
  • "platform_account_id": "8301de71-1ac1-4edb-8119-73ff911eb9ad",
  • "name": "string",
  • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
  • "description": "string",
  • "external_account_id": "string",
  • "currency": "string",
  • "balance": 0
}
Update platform account
Updates a RippleNet platform account, which represents a real-world account owned by a financial entity (e.g. Bank, Exchange or Wallet provider).


SecurityBearer 
Request 
path Parameters
platform_account_id
required
string <uuid> 
ID of the platform account you want to update.


 
Request Body schema: application/json
required
name
string
Name of the platform account.


 
platform_id
string <uuid> 
The unique identifier for the RippleNet platform where this account is defined.


 
description
string  <= 512 characters 
A short description of the platform account.


 
external_account_id
string
Unique reference identifier for the real world account which is represented by this platform account.


 
currency
string  <= 3 characters 
The currency of the account. Ripple recommends using ISO-4217 currency codes.


 
Responses 
200
Successfully updated RippleNet platform account.


400
Bad request.


put/config/platforms/accounts/{platform_account_id}
Request samples 
application/json
{
  • "name": "string",
  • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
  • "description": "string",
  • "external_account_id": "string",
  • "currency": "str"
}
Response samples 
application/json
{
  • "platform_account_id": "8301de71-1ac1-4edb-8119-73ff911eb9ad",
  • "name": "string",
  • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
  • "description": "string",
  • "external_account_id": "string",
  • "currency": "string",
  • "balance": 0
}
Delete platform account by platform account ID
Deletes a RippleNet platform account by its platform account ID.


SecurityBearer 
Request 
path Parameters
platform_account_id
required
string <uuid> 
ID of the platform account you want to delete.


 
Responses 
204
Deleted platform account successfully.


400
Bad request.


delete/config/platforms/accounts/{platform_account_id}
Request samples 
Response samples 
application/json
{}
Get platform accounts balances
Get balances for local Platform Accounts


SecurityBearer 
Responses 
200
Successfully returned balances for all platform accounts.


400
Bad request.


get/monitor/platform/accounts/balances
Request samples 
Response samples 
application/json
{
  • "platforms": [
    • {
      • "platform_id": "f41a0584-7f4a-481e-9327-001efe2ebd2c",
      • "name": "string",
      • "institution": "string",
      • "type": "string",
      • "servicer_code": "string",
      • "accounts": [
        • {
          • "platform_account_id": "8301de71-1ac1-4edb-8119-73ff911eb9ad",
          • "name": "string",
          • "external_account_id": "string",
          • "currency": "string",
          • "total_balance": 0,
          • "available_balance": 0,
          • "errors": [
            • "string"
            ]
          }
        ]
      }
    ]
}
Get platform account statement
Get statement for a specified Platform Account


SecurityBearer 
Request 
path Parameters
platformAccountId
required
string
The RippleNet platform account ID that you want to get a statement for. Example: bitso


 
query Parameters
start-date
required
string
The lower bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC. For example, 2018-08-06T23:13:55.997Z.


 
end-date
required
string
The upper bound of the date-time range you want to return statement information for, as an ISO-8601 timestamp in UTC For example, 2018-08-06T23:15:13.218Z.


 
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  10
Number of payment and transfer objects to return per page.


 
Responses 
200
Successfully returned statement for a specified platform account.


400
Bad request.


get/monitor/platform/accounts/{platformAccountId}/statement
Request samples 
Response samples 
application/json
{
  • "account_name": "trans_usd_sf",
  • "start_datetime": "2018-08-06T23:13:55.997Z",
  • "end_datetime": "2020-08-06T23:13:55.997Z",
  • "generated_at": "2019-10-01T21:58:23.621Z",
  • "currency": "USD",
  • "owner": "rn.us.ca.san_francisco",
  • "opening_balance": 0,
  • "closing_balance": -909,
  • "transactions": {
    • "content": [
      • {
        • "transaction_id": "9eca588f-e89d-4629-82fa-da9c4646310f",
        • "transaction_type": "PAYMENT",
        • "transaction_state": "COMPLETED",
        • "balance_change": -15,
        • "balance_result": -909,
        • "created_at": "2019-10-01T21:28:28.354Z",
        • "end_to_end_id": "91ecb6bd-4dd8-4b53-a900-72b79f3064e4",
        • "internal_id": "8afd8e99-4ad4-4f4e-9bb7-018ad8c3a89c",
        • "venue_id": "nz7RpAujYgnQtjEM",
        • "transaction_hash": "DB0AFC09E0A94FC1D11F8CBABA48A184E27094F8DD32FCBC46F316E98011E2A6",
        • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
        • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
        • "balance_change_created_at": "2019-10-01T21:28:28.354Z",
        • "sender_address": "rn.us.ca.san_francisco",
        • "receiver_address": "rn.mx.mexico"
        }
      ],
    • "total_elements": 1,
    • "sort": "string",
    • "first": true,
    • "last": true,
    • "number": 0,
    • "numberOfElements": 1,
    • "size": 10,
    • "totalPages": 1
    }
}
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.





Get all pool accounts
Returns a list of all pool accounts on a RippleNet node.


SecurityBearer 
Responses 
200
List of all pool accounts.


400
Bad request.


get/config/pool_accounts
Request samples 
Response samples 
application/json
[
  • {
    • "pool_account_id": "8bb116e3-309b-4f1e-9150-ea3b31a4e22f",
    • "pool_account_name": "string",
    • "currency": "string",
    • "description": "string",
    • "owner": "rn.us.ca.san_francisco",
    • "linkedAccountNames": [
      • "string"
      ]
    }
]
Get pool account by pool account ID
Get a pool account by its pool account ID.


SecurityBearer 
Request 
path Parameters
pool_account_id
required
string <uuid> 
Unique name to identify the pool account.


 
Responses 
200
Returns pool account for the given pool account ID.


400
Bad request.


get/config/pool_accounts/{pool_account_id}
Request samples 
Response samples 
application/json
{
  • "pool_account_id": "8bb116e3-309b-4f1e-9150-ea3b31a4e22f",
  • "pool_account_name": "string",
  • "currency": "string",
  • "description": "string",
  • "owner": "rn.us.ca.san_francisco",
  • "linkedAccountNames": [
    • "string"
    ]
}
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.





List quote expiries
Returns all configured quote expiries.


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
Zero-based index of the page number of results.


 
size
integer
 Default:  10
Number of payments returned per page.


 
Responses 
200
Successful response


400
Bad request.


get/config/payments/quote_expiries
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "quote_ttl": 5900,
      • "sending_partner": "rn.us.ca.san_francisco",
      • "receiving_partner": "rn.us.tx.austin",
      • "currency": "USD",
      • "id": 2
      }
    ]
}
Create quote expiry
Creates a quote expiration window, or time to live (ttl), in seconds.


SecurityBearer 
Request 
Request Body schema: application/json
required
quote_ttl
number
Quote expiration window, or time to live (ttl), in seconds. To calculate the quote expiration date, xCurrent adds this value to the quote creation timestamp.


 
sending_partner
string
RippleNet address of the sender, in the format ripplenetaddress. For example, rn.us.sf.san_francisco.


 
receiving_partner
string
RippleNet address of the receiver, in the format ripplenetaddress. For example, rn.us.ny.new_york.


 
currency
string
currency of the exchange rate.


 
id
integer
id of quote expiry object


 
Responses 
200
Successfully created the quote expiration window.


400
Bad request.


post/config/payments/quote_expiries
Request samples 
application/json
{
  • "quote_ttl": 5900,
  • "sending_partner": "rn.us.ca.san_francisco",
  • "receiving_partner": "rn.us.tx.austin",
  • "currency": "USD",
  • "id": 2
}
Response samples 
application/json
{
  • "quote_ttl": 5900,
  • "sending_partner": "rn.us.ca.san_francisco",
  • "receiving_partner": "rn.us.tx.austin",
  • "currency": "USD",
  • "id": 2
}
Get quote expiry
Gets the time to live (ttl) of a quote expiry in seconds.


SecurityBearer 
Request 
path Parameters
quote_expiry_id
required
integer <int64> 
The ID of the quote expiry you want returned.


 
Responses 
200
Successfully returned a quote expiry.


400
Bad request.


get/config/payments/quote_expiries/{quote_expiry_id}
Request samples 
Response samples 
application/json
{
  • "quote_ttl": 5900,
  • "sending_partner": "rn.us.ca.san_francisco",
  • "receiving_partner": "rn.us.tx.austin",
  • "currency": "USD",
  • "id": 2
}
Update quote expiry
Updates the time to live (ttl) of a quote expiry in seconds.


SecurityBearer 
Request 
path Parameters
quote_expiry_id
required
integer <int64> 
Provide the quote_expiry_id of the quote expiry you want to update.


 
Request Body schema: application/json
required
quote_ttl
number
Quote expiration window, or time to live (ttl), in seconds. To calculate the quote expiration date, xCurrent adds this value to the quote creation timestamp.


 
sending_partner
string
RippleNet address of the sender, in the format ripplenetaddress. For example, rn.us.sf.san_francisco.


 
receiving_partner
string
RippleNet address of the receiver, in the format ripplenetaddress. For example, rn.us.ny.new_york.


 
currency
string
currency of the exchange rate.


 
id
integer
id of quote expiry object


 
Responses 
200
Successfully updated quote expiry.


400
Bad request.


put/config/payments/quote_expiries/{quote_expiry_id}
Request samples 
application/json
{
  • "quote_ttl": 5900,
  • "sending_partner": "rn.us.ca.san_francisco",
  • "receiving_partner": "rn.us.tx.austin",
  • "currency": "USD",
  • "id": 2
}
Response samples 
application/json
{
  • "quote_ttl": 5900,
  • "sending_partner": "rn.us.ca.san_francisco",
  • "receiving_partner": "rn.us.tx.austin",
  • "currency": "USD",
  • "id": 2
}
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.





Accept quote
Accepts a quote ID to start the payment process.


SecurityBearer 
Request 
Request Body schema: application/json
required
The JSON object to include in your request to accept a quote that you want to advance as a payment.


quote_id
required
string <uuid> 
ID of the quote to accept and continue as a payment.


 
sender_end_to_end_id
string  <= 128 characters 
ID that the sender can specify. Persisted on all RippleNet instances that participate in the payment.


 
internal_id
string  <= 128 characters 
Internal ID that the sender can specify. Only visible to the sender. Only the sending RippleNet instance stores this ID.


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


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


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


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


412
Quote expiry has passed.


post/payments/accept
Request samples 
application/json
{
  • "quote_id": "9bb53b3b-a774-43e2-9a1b-f18fbc3640f7",
  • "sender_end_to_end_id": "string",
  • "internal_id": "string",
  • "user_info": { }
}
Response samples 
application/json
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    • "sender_end_to_end_id": "string",
    • "created_at": "2019-10-01T18:18:13.665Z",
    • "expires_at": "2019-10-01T18:55:22.824Z",
    • "quote": {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      },
    • "fee_info": {
      • "nodes": {
        • "property1": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ],
        • "property2": [
          • {
            • "fee_value": 0,
            • "fee_currency": "string",
            • "category": "string",
            • "fee_description": "string"
            }
          ]
        },
      • "total_fees": [
        • {
          • "total_fee": 0,
          • "fee_currency": "string"
          }
        ]
      }
    },
  • "ripplenet_info": [
    • {
      • "node_address": "rn.us.ny.new_york",
      • "settlement_declined": [
        • {
          • "info": "L001",
          • "created_at": "2018-04-06T20:33:35Z"
          }
        ]
      }
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "REGULAR",
  • "returns_payment_with_id": "a69b322f-faa4-4531-bcff-897e5839c130",
  • "returned_by_payment_with_id": "c929a87b-81b8-4878-b21c-1aeaa4fe9276",
  • "execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "liquidation_details": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "status": "string",
    • "failure_reason": "string",
    • "failure_count": 0
    },
  • "push_forward_execution_results": [
    • {
      • "execution_result_id": "06f6d4e2-3523-4d17-92fd-53192a06207f",
      • "execution_timestamp": "2019-10-01T18:24:29.867Z",
      • "execution_result_type": "TRANSFER",
      • "execution_result_order": 1,
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "sending_amount": 498,
      • "receiving_amount": 498,
      • "sending_fee": 2,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string",
      • "intermediary_delta": 0.2,
      • "incentive_type": "firm",
      • "incentive_value": 0.2,
      • "transaction_hash": 5.5467794184785867e+76,
      • "venue_id": "nz7RpAujYgnQtjEM",
      • "fiat_adjusted_value": 0.02,
      • "odl_payment_id": "string"
      }
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "locked_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "returned_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    • "connector_role": "RECEIVING",
    • "labels": [
      • {
        • "label": "string"
        }
      ],
    • "internal_id": "string"
    },
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "locked": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "lock_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_accept": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "retry_settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "settlement_declined": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "executed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "completed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "forwarded": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "returned": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ]
}
Get quotes
Gets a list of quotes.


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  20
Number of objects to return per page.


 
Responses 
200
Successfully returned array of quotes.


400
Bad request.


get/quotes
Request samples 
Response samples 
application/json
[
  • {
    • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
    • "created_at": "2020-01-29T20:59:44.925Z",
    • "expires_at": "2020-01-29T21:29:44.925Z",
    • "type": "SENDER_AMOUNT",
    • "price_guarantee": "FIRM",
    • "sender_address": "sf@rn.us.ca.san_francisco",
    • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
    • "amount": "1",
    • "currency_code": "USD",
    • "currency_code_filter": "EUR",
    • "service_type": "string",
    • "quote_elements": [
      • {
        • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
        • "quote_element_type": "EXCHANGE",
        • "quote_element_order": "1",
        • "sender_address": "sf@rn.us.ca.san_francisco",
        • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
        • "sending_amount": 1,
        • "receiving_amount": 355,
        • "sending_fee": 0,
        • "receiving_fee": 0,
        • "sending_currency_code": "USD",
        • "receiving_currency_code": "GBP",
        • "fx_rate": {
          • "rate": 3.25,
          • "base_currency_code": "USD",
          • "counter_currency_code": "GBP",
          • "type": "buy"
          },
        • "transfer_currency_code": "string"
        }
      ],
    • "liquidity_warning": "string",
    • "payment_method": "LOCAL_RAILS",
    • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
    • "payout_method_info": {
      • "payout_method_name": "Cash Payout",
      • "payout_method_category": "BOOK_TRANSFER",
      • "description": "local rails",
      • "estimated_time_to_credit": "3 days"
      }
    }
]
Get quote by quote ID
Gets a quote by ID.


SecurityBearer 
Request 
path Parameters
quote_id
required
string <uuid> 
Unique identifier of the quote you want to retrieve.


 
Responses 
200
Successfully retrieved quote.


400
Bad request. Quote ID is either invalid or not found.


get/quotes/{quote_id}
Request samples 
Response samples 
application/json
{
  • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
  • "created_at": "2020-01-29T20:59:44.925Z",
  • "expires_at": "2020-01-29T21:29:44.925Z",
  • "type": "SENDER_AMOUNT",
  • "price_guarantee": "FIRM",
  • "sender_address": "sf@rn.us.ca.san_francisco",
  • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
  • "amount": "1",
  • "currency_code": "USD",
  • "currency_code_filter": "EUR",
  • "service_type": "string",
  • "quote_elements": [
    • {
      • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
      • "quote_element_type": "EXCHANGE",
      • "quote_element_order": "1",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "sending_amount": 1,
      • "receiving_amount": 355,
      • "sending_fee": 0,
      • "receiving_fee": 0,
      • "sending_currency_code": "USD",
      • "receiving_currency_code": "GBP",
      • "fx_rate": {
        • "rate": 3.25,
        • "base_currency_code": "USD",
        • "counter_currency_code": "GBP",
        • "type": "buy"
        },
      • "transfer_currency_code": "string"
      }
    ],
  • "liquidity_warning": "string",
  • "payment_method": "LOCAL_RAILS",
  • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
  • "payout_method_info": {
    • "payout_method_name": "Cash Payout",
    • "payout_method_category": "BOOK_TRANSFER",
    • "description": "local rails",
    • "estimated_time_to_credit": "3 days"
    }
}
Create quote collection
Creates a collection of quotes for a proposed payment.


SecurityBearer 
Request 
Request Body schema: application/json
required
sending_address
required
string
RippleNet account name and address of the sender.


Format: accountname@ripplenetaddress


Example: new_york@rn.us.ny.new_york


 
receiving_address
required
string
RippleNet account name and address of the receiver.


Format: accountname@ripplenetaddress


Example: new_york@rn.us.ny.new_york


 
amount
required
string  >= 1 
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





 
currency
required
string
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





 
quote_type
required
string
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


 
sender_or_receiver_currency
string
Currency code of the sender or receiver based on quote_type.


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


 
custom_fee
number
Custom fee for the sending account.


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


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


 
quote_route
Array 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


 
payment_method
string
Payout method for the quote.


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


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


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


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


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


 
force_path_finding_and_liquidity_path_finding
boolean
 Default:  false
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.


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


 Enum Value Description
REAL_TIME_GROSS_SETTLEMENT_SYSTEM
Real-time gross settlement system


REAL_TIME_NET_SETTLEMENT_SYSTEM
Real-time net settlement system


MASS_NET_PAYMENT_SYSTEM
Mass net payment system


BOOK_TRANSFER
Book transfer


CASH_PAYOUT
Cash payout


WALLET_PAYMENT
Wallet payment


OTHER
Other


 
sender_segregated_account
string  <= 254 characters 
RippleNet account name and address of the sender owned account at receiver to be used for failure conversion (in case of payment failure).


Format: accountname@ripplenetaddress


Example: new_york@rn.us.ny.new_york


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


 
quote_filter_types
Array of strings
Filter on a type of quote.


Items Enum Value Description
LIQUIDITY_WARNINGS
Filter for liquidity warnings


QUOTE_ERRORS
Filter for quote errors


 
Responses 
200
Successfully returned quote collection.


400
Bad request.


post/quote_collections
Request samples 
application/json
{
  • "sending_address": "sf@rn.us.ca.san_francisco",
  • "receiving_address": "sf_gbp@rn.us.ca.san_francisco",
  • "amount": "1",
  • "currency": "USD",
  • "quote_type": "SENDER_AMOUNT",
  • "sender_or_receiver_currency": "USD",
  • "custom_fee": 0,
  • "custom_rate": {
    • "rate": 0,
    • "base_currency": "string",
    • "counter_currency": "string",
    • "rate_type": "buy"
    },
  • "quote_route": [
    • "rn.us.ca.san_francisco",
    • "rn.us.tx.austin",
    • "rn.us.ny.new_york"
    ],
  • "payment_method": "string",
  • "enable_quote_per_payout_method": true,
  • "digital_asset_origination": false,
  • "force_path_finding_and_liquidity_path_finding": false,
  • "payout_method_category": "BOOK_TRANSFER",
  • "sender_segregated_account": "conct_php_receiver_coins_sender@receiver",
  • "quote_limit": 0,
  • "quote_filter_types": [
    • "LIQUIDITY_WARNINGS"
    ]
}
Response samples 
application/json
{
  • "quote_collection_id": "4711728c-cd35-49ec-96a5-72732b4333ec",
  • "quotes": [
    • {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      }
    ],
  • "quote_errors": [
    • {
      • "failed_path": [
        • {
          • "source": "string",
          • "destination": "string",
          • "source_currency": "string",
          • "destination_currency": "string",
          • "account_liquidity_relationship_id": "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6",
          • "peer_liquidity_relationship_id": "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"
          }
        ],
      • "error_origin": "string",
      • "error_message": "string"
      }
    ]
}
Get quote collection by ID
Gets a quote collection that was created for a proposed payment.


SecurityBearer 
Request 
path Parameters
quote_collection_id
required
string <uuid> 
The ID of the quote collection you want returned.


 
Responses 
200
Successfully returned a quote collection.


400
Bad request.


get/quote_collections/{quote_collection_id}
Request samples 
Response samples 
application/json
{
  • "quote_collection_id": "4711728c-cd35-49ec-96a5-72732b4333ec",
  • "quotes": [
    • {
      • "quote_id": "2a547e56-4aac-4375-86a8-8b3e7014801d",
      • "created_at": "2020-01-29T20:59:44.925Z",
      • "expires_at": "2020-01-29T21:29:44.925Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "sf@rn.us.ca.san_francisco",
      • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
      • "amount": "1",
      • "currency_code": "USD",
      • "currency_code_filter": "EUR",
      • "service_type": "string",
      • "quote_elements": [
        • {
          • "quote_element_id": "259189e7-cb14-42e7-99ef-375f3285e356",
          • "quote_element_type": "EXCHANGE",
          • "quote_element_order": "1",
          • "sender_address": "sf@rn.us.ca.san_francisco",
          • "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
          • "sending_amount": 1,
          • "receiving_amount": 355,
          • "sending_fee": 0,
          • "receiving_fee": 0,
          • "sending_currency_code": "USD",
          • "receiving_currency_code": "GBP",
          • "fx_rate": {
            • "rate": 3.25,
            • "base_currency_code": "USD",
            • "counter_currency_code": "GBP",
            • "type": "buy"
            },
          • "transfer_currency_code": "string"
          }
        ],
      • "liquidity_warning": "string",
      • "payment_method": "LOCAL_RAILS",
      • "payment_method_fields": "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}",
      • "payout_method_info": {
        • "payout_method_name": "Cash Payout",
        • "payout_method_category": "BOOK_TRANSFER",
        • "description": "local rails",
        • "estimated_time_to_credit": "3 days"
        }
      }
    ],
  • "quote_errors": [
    • {
      • "failed_path": [
        • {
          • "source": "string",
          • "destination": "string",
          • "source_currency": "string",
          • "destination_currency": "string",
          • "account_liquidity_relationship_id": "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6",
          • "peer_liquidity_relationship_id": "480e3a6f-3bcd-48cd-9ce9-9d940aa3c9c6"
          }
        ],
      • "error_origin": "string",
      • "error_message": "string"
      }
    ]
}
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.





Get rates
Gets a list of configured exchange rates.


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  20
Number of objects to return per page.


 
Responses 
200
Successfully returned list of rates.


400
Bad request.


get/config/rates
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "rate_id": "328b3e50-7983-46d5-94a0-ef004d78db1d",
      • "expiration_offset": 95000,
      • "order_type": "buy",
      • "rate_scale": 9,
      • "rate": 0.89,
      • "base_currency": "USD",
      • "counter_currency": "GBP",
      • "source_currency": "USD",
      • "destination_currency": "GBP",
      • "source_ledger": "rn.eur.uk.london",
      • "destination_ledger": "rn.eur.uk.london",
      • "source_ledger_account": "alias_usd_lon",
      • "destination_ledger_account": "conct_gbp_lon",
      • "created_date": "2019-08-24T14:15:22Z",
      • "expires_at": "2019-08-24T14:15:22Z",
      • "lower_limit": 0,
      • "upper_limit": 1000,
      • "payout_method": "LOCAL_RAILS",
      • "value_type": "MARGIN",
      • "margin_type": "BPS"
      }
    ]
}
Create rate
Creates an exchange rate for a specified currency pair.


Example - Applying a margin to the live FX rate:

A USD-GBP live FX rate of 0.80 is provided by a third-party rate provider and you want to reduce that rate by 20 BPS. In this API call, you would set "value_type": "MARGIN", then "margin_type": "BPS", and "rate": "20". After that, during the Get quotes call, the final FX rate will be calculated as 0.80*(1-(20/10000))=0.7984 and then applied during quote creation.


SecurityBearer 
Request 
Request Body schema: application/json
required
expiration_offset
required
integer
Set to the amount of time in milliseconds that the rate is valid for after the rate's created_date value. Set to 0 to indicate that the rate does not expire. The value returned in the response object for this field is null. Refer to the expires_at value in the response object to verify your expiration offset timing.


 
order_type
required
string
Set to the order type for the exchange rate.


 Enum: "buy" "sell"  
rate
required
number
This value of this field represents either rate or margin based on what you specify in the value_type field. 


If you specify value_type=rate, set the value of this field to the exchange rate for a base and counter currency. The rate can use up to 6 decimal
places. 


If you specify value_type=margin, set the value of this field depending on the unit of margin you specified in the margin_type field.


 
base_currency
required
string
Set to the base currency of the exchange rate.


 
counter_currency
required
string
Set to the counter currency of the exchange rate.


 
object (RatePerLedgerRequest) 
Use the ledger request object to create an exchange rate that applies to exchanges between a specific source ledger and destination ledger.


 
object (RatePerAccountRequest) 
Use the account request object to create an exchange rate that applies to exchanges between a specific source ledger account and destination ledger account.


 
lower_limit
number
To create a slab-based exchange rate, provide the lower limit of the slab. You must also provide an upper_limit value.


 
upper_limit
number
To create a slab-based exchange rate, provide the upper limit of the slab. You must also provide a lower_limit value.


 
payout_method
string
The payout method for the rate.


 
value_type
string
Specify whether you want to use a live exchange rate (MARGIN) or an exchange rate manually configured by Ripple (RATE). If you set this value to MARGIN, you must also provide margin_type.


 Enum: "MARGIN" "RATE"  
margin_type
string
Specify the unit of margin to be applied (BPS) in addition to the rate provided by Ripple. Specify this field only if you set value_type = MARGIN.


 Value: "BPS"  
Responses 
200
Successfully created rate.


400
Request error.


post/config/rates
Request samples 
application/json
{
  • "expiration_offset": 95000,
  • "order_type": "buy",
  • "rate": 0.89,
  • "base_currency": "USD",
  • "counter_currency": "GBP",
  • "ledger": {
    • "source_ledger": "rn.eur.uk.london",
    • "destination_ledger": "rn.eur.uk.london"
    },
  • "account": {
    • "source_ledger": "rn.eur.uk.london",
    • "destination_ledger": "rn.eur.uk.london",
    • "source_ledger_account": "alias_usd_lon",
    • "destination_ledger_account": "conct_gbp_lon"
    },
  • "lower_limit": 0,
  • "upper_limit": 1000,
  • "payout_method": "LOCAL_RAILS",
  • "value_type": "MARGIN",
  • "margin_type": "BPS"
}
Response samples 
application/json
{
  • "rate_id": "328b3e50-7983-46d5-94a0-ef004d78db1d",
  • "expiration_offset": 95000,
  • "order_type": "buy",
  • "rate_scale": 9,
  • "rate": 0.89,
  • "base_currency": "USD",
  • "counter_currency": "GBP",
  • "source_currency": "USD",
  • "destination_currency": "GBP",
  • "source_ledger": "rn.eur.uk.london",
  • "destination_ledger": "rn.eur.uk.london",
  • "source_ledger_account": "alias_usd_lon",
  • "destination_ledger_account": "conct_gbp_lon",
  • "created_date": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "lower_limit": 0,
  • "upper_limit": 1000,
  • "payout_method": "LOCAL_RAILS",
  • "value_type": "MARGIN",
  • "margin_type": "BPS"
}
Get rate by ID
Gets a configured exchange rate by ID.


SecurityBearer 
Request 
path Parameters
rate_id
required
string <uuid> 
Provide the rate_id of the exchange rate you want to return.


 
Responses 
200
Sucessfully returned rate.


404
Rate not found.


get/config/rates/{rate_id}
Request samples 
Response samples 
application/json
{
  • "rate_id": "328b3e50-7983-46d5-94a0-ef004d78db1d",
  • "expiration_offset": 95000,
  • "order_type": "buy",
  • "rate_scale": 9,
  • "rate": 0.89,
  • "base_currency": "USD",
  • "counter_currency": "GBP",
  • "source_currency": "USD",
  • "destination_currency": "GBP",
  • "source_ledger": "rn.eur.uk.london",
  • "destination_ledger": "rn.eur.uk.london",
  • "source_ledger_account": "alias_usd_lon",
  • "destination_ledger_account": "conct_gbp_lon",
  • "created_date": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "lower_limit": 0,
  • "upper_limit": 1000,
  • "payout_method": "LOCAL_RAILS",
  • "value_type": "MARGIN",
  • "margin_type": "BPS"
}
Update rate
Updates an existing exchange rate. With this call, you can change value_type from RATE to MARGIN (and vice versa), change the actual rate value of the specified value type, or both.


Example - Updating an existing margin applied to the live FX rate:

A USD-GBP live FX rate of 0.80 is provided by a third-party rate provider and you currently reduce that rate by 20 BPS. You now want to change it and reduce it by 10 BPS instead. To do so, set "rate": "10" in the request. Once the change is applied, the final FX rate is calculated as 0.80*(1-(10/10000))=0.7992 during the Get quotes call, and then applied during quote creation.


SecurityBearer 
Request 
path Parameters
rate_id
required
string <uuid> 
Provide the rate_id of the exchange rate you want to update.


 
Request Body schema: application/json
required
expiration_offset
required
integer
Set to the amount of time in milliseconds that the rate is valid for after the rate's created_date value. Set to 0 to indicate that the rate does not expire. The value returned in the response object for this field is null. Refer to the expires_at value in the response object to verify your expiration offset timing.


 
order_type
required
string
Set to the order type for the exchange rate.


 Enum: "buy" "sell"  
rate
required
number
This value of this field represents either rate or margin based on what you specify in the value_type field. 


If you specify value_type=rate, set the value of this field to the exchange rate for a base and counter currency. The rate can use up to 6 decimal
places. 


If you specify value_type=margin, set the value of this field depending on the unit of margin you specified in the margin_type field.


 
base_currency
required
string
Set to the base currency of the exchange rate.


 
counter_currency
required
string
Set to the counter currency of the exchange rate.


 
object (RatePerLedgerRequest) 
Use the ledger request object to create an exchange rate that applies to exchanges between a specific source ledger and destination ledger.


 
object (RatePerAccountRequest) 
Use the account request object to create an exchange rate that applies to exchanges between a specific source ledger account and destination ledger account.


 
lower_limit
number
To create a slab-based exchange rate, provide the lower limit of the slab. You must also provide an upper_limit value.


 
upper_limit
number
To create a slab-based exchange rate, provide the upper limit of the slab. You must also provide a lower_limit value.


 
payout_method
string
The payout method for the rate.


 
value_type
string
Specify whether you want to use a live exchange rate (MARGIN) or an exchange rate manually configured by Ripple (RATE). If you set this value to MARGIN, you must also provide margin_type.


 Enum: "MARGIN" "RATE"  
margin_type
string
Specify the unit of margin to be applied (BPS) in addition to the rate provided by Ripple. Specify this field only if you set value_type = MARGIN.


 Value: "BPS"  
Responses 
200
Successfully updated rate.


400
Request error.


put/config/rates/{rate_id}
Request samples 
application/json
{
  • "expiration_offset": 95000,
  • "order_type": "buy",
  • "rate": 0.89,
  • "base_currency": "USD",
  • "counter_currency": "GBP",
  • "ledger": {
    • "source_ledger": "rn.eur.uk.london",
    • "destination_ledger": "rn.eur.uk.london"
    },
  • "account": {
    • "source_ledger": "rn.eur.uk.london",
    • "destination_ledger": "rn.eur.uk.london",
    • "source_ledger_account": "alias_usd_lon",
    • "destination_ledger_account": "conct_gbp_lon"
    },
  • "lower_limit": 0,
  • "upper_limit": 1000,
  • "payout_method": "LOCAL_RAILS",
  • "value_type": "MARGIN",
  • "margin_type": "BPS"
}
Response samples 
application/json
{
  • "rate_id": "328b3e50-7983-46d5-94a0-ef004d78db1d",
  • "expiration_offset": 95000,
  • "order_type": "buy",
  • "rate_scale": 9,
  • "rate": 0.89,
  • "base_currency": "USD",
  • "counter_currency": "GBP",
  • "source_currency": "USD",
  • "destination_currency": "GBP",
  • "source_ledger": "rn.eur.uk.london",
  • "destination_ledger": "rn.eur.uk.london",
  • "source_ledger_account": "alias_usd_lon",
  • "destination_ledger_account": "conct_gbp_lon",
  • "created_date": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "lower_limit": 0,
  • "upper_limit": 1000,
  • "payout_method": "LOCAL_RAILS",
  • "value_type": "MARGIN",
  • "margin_type": "BPS"
}
Delete rate
Deletes an exchange rate. Once deleted, an exchange rate cannot be accessed.


SecurityBearer 
Request 
path Parameters
rate_id
required
string <uuid> 
Provide the rate_id of the exchange rate you want to delete.


 
Responses 
200
Successfully deleted rate.


400
Bad request.


delete/config/rates/{rate_id}
Request samples 
Response samples 
application/json
{}
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.





Get requests for payment
Gets requests for payment that match the query parameters.


SecurityBearer 
Request 
query Parameters
end_to_end_id
string
Optional parameter to filter results matching this endToEndId value.


 
state
string
State by which to filter results.


 Enum: "REQUESTED" "ACCEPTED" "FAILED"  
sender_address
string
Field to filter results matching this senderAddress value.


 
receiver_address
string
Field to filter results matching this receiverAddress value.


 
payment_id
string <uuid> 
Field to filter results matching this paymentId value.


 
before
string
Filters for requests for payment whose range_field column value is before this specified time stamp (not inclusive). You can also specify after to create a time range between after and before. If before is specified, range_field must also be specified


 
after
string
Filters for requests for payment whose range_field column value is after this specified time stamp (not inclusive). You can also specify before to create a time range between after and before. If after is specified, range_field must also be specified.


 
range_field
string
Designates the column name of the requests for payment database table that is used for filtering payments before/after/between time stamps. For example, if you specify range_field=MODIFIED_AT, you would specify a time stamp (in the 24 character ISO 8601 YYYY-MM-DDTHH:mm:ss.sssZ format used in request for payment objects) as the value for before and/or after to fetch request for payment before, after, or between the specified time range(s) (not inclusive). If range_field is specified, before and/or after must also be specified.


 Enum: "CREATED_AT" "MODIFIED_AT"  
sort_field
string
Field to use to sort results.


 Enum: "CREATED_AT" "MODIFIED_AT"  
sort_direction
string
 Default:  "DESC"
Sorts result according to the specified direction.


 Enum: "ASC" "DESC"  
page
integer
 Default:  0
Zero-based index of the page number of results.


 
size
integer
 Default:  10
The number of payments per page.


 
Responses 
200
Successfully retrieves requests for payment matching query parameters.


400
Bad request.


get/request_for_payment
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "request_for_payment_id": "1bf93760-ef69-4697-b2b4-47d9e1c42aa7",
      • "request_for_payment_state": "REQUESTED",
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "trans_gbp_lon@rn.eur.uk.london",
      • "amount": 100.01,
      • "currency": "USD",
      • "quote_type": "SENDER_AMOUNT",
      • "end_to_end_id": "string",
      • "user_info": [
        • {
          • "node_address": "string",
          • "requested": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "accepted": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ],
          • "failed": [
            • {
              • "json": { },
              • "created_at": "2019-08-24T14:15:22Z",
              • "subState": "EXECUTING"
              }
            ]
          }
        ],
      • "created_at": "2019-08-24T14:15:22Z",
      • "payment_id": "5492648d-2132-4e70-9ded-2fc86f22b321"
      }
    ]
}
Send request for payment
Sends a new request for payment.


SecurityBearer 
Request 
Request Body schema: application/json
required
The request object to initiate a new request for payment.


sender_address
required
string
RippleNet address of the node that is receiving the request for payment, or the eventual sender of the payment.


 
receiver_address
required
string
RippleNet address of the node that is sending the request for payment, or the eventual receiver of the payment.


 
amount
required
number
Amount requested to be paid.


 
currency
required
string
Currency code for the amount value.


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


 Enum: "SENDER_AMOUNT" "RECEIVER_AMOUNT" "SENDER_INSTITUTION_AMOUNT" "RECEIVER_INSTITUTION_AMOUNT"  
end_to_end_id
string
ID that the eventual payment receiver can specify. Persisted on all rippleNet node instances (namely, the sender and receiver of the payment) that participate in the request for payment.


 
user_info
object
User-provided data with arbitrary key/value pairs.


 
Responses 
200
Successfully sent a request for payment resulting in a request for payment object in the REQUESTED state.


400
Bad request.


post/request_for_payment
Request samples 
application/json
{
  • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
  • "receiver_address": "trans_gbp_lon@rn.eur.uk.london",
  • "amount": 100.01,
  • "currency": "USD",
  • "quote_type": "SENDER_AMOUNT",
  • "end_to_end_id": "string",
  • "user_info": { }
}
Response samples 
application/json
{
  • "request_for_payment_id": "1bf93760-ef69-4697-b2b4-47d9e1c42aa7",
  • "request_for_payment_state": "REQUESTED",
  • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
  • "receiver_address": "trans_gbp_lon@rn.eur.uk.london",
  • "amount": 100.01,
  • "currency": "USD",
  • "quote_type": "SENDER_AMOUNT",
  • "end_to_end_id": "string",
  • "user_info": [
    • {
      • "node_address": "string",
      • "requested": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_id": "5492648d-2132-4e70-9ded-2fc86f22b321"
}
Get request for payment by ID
Gets a request for payment by request for payment ID.


SecurityBearer 
Request 
path Parameters
request_for_payment_id
required
string <uuid> 
Unique identifier of the request for payment to retrieve.


 
Responses 
200
Successfully retrieves a request for payment by its ID.


400
Bad request.


get/request_for_payment/{request_for_payment_id}
Request samples 
Response samples 
application/json
{
  • "request_for_payment_id": "1bf93760-ef69-4697-b2b4-47d9e1c42aa7",
  • "request_for_payment_state": "REQUESTED",
  • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
  • "receiver_address": "trans_gbp_lon@rn.eur.uk.london",
  • "amount": 100.01,
  • "currency": "USD",
  • "quote_type": "SENDER_AMOUNT",
  • "end_to_end_id": "string",
  • "user_info": [
    • {
      • "node_address": "string",
      • "requested": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_id": "5492648d-2132-4e70-9ded-2fc86f22b321"
}
Accept request for payment
Accepts a request for payment.


SecurityBearer 
Request 
path Parameters
request_for_payment_id
required
string <uuid> 
Unique identifier of the request for payment to accept.


 
Request Body schema: application/json
required
The request object to accept a request for payment.


payment_id
required
string <uuid> 
Unique identifier of payment associated with the request for payment.


 
user_info
object
User-provided data with arbitrary key/value pairs.


 
Responses 
200
Successfully accepts a request for payment resulting in a request for payment object in the ACCEPTED state.


400
Bad request.


post/request_for_payment/{request_for_payment_id}/accept
Request samples 
application/json
{
  • "payment_id": "1bf93760-ef69-4697-b2b4-47d9e1c42aa7",
  • "user_info": { }
}
Response samples 
application/json
{
  • "request_for_payment_id": "1bf93760-ef69-4697-b2b4-47d9e1c42aa7",
  • "request_for_payment_state": "REQUESTED",
  • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
  • "receiver_address": "trans_gbp_lon@rn.eur.uk.london",
  • "amount": 100.01,
  • "currency": "USD",
  • "quote_type": "SENDER_AMOUNT",
  • "end_to_end_id": "string",
  • "user_info": [
    • {
      • "node_address": "string",
      • "requested": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_id": "5492648d-2132-4e70-9ded-2fc86f22b321"
}
Fail request for payment
Fails a request for payment.


SecurityBearer 
Request 
path Parameters
request_for_payment_id
required
string <uuid> 
Unique identifier of the request for payment to fail.


 
Request Body schema: application/json
required
The request object to fail a request for payment.


user_info
object
User-provided data with arbitrary key/value pairs.


 
Responses 
200
Successfully fails a request for payment resulting in a request for payment object in the FAILED state.


400
Bad request.


post/request_for_payment/{request_for_payment_id}/fail
Request samples 
application/json
{
  • "user_info": { }
}
Response samples 
application/json
{
  • "request_for_payment_id": "1bf93760-ef69-4697-b2b4-47d9e1c42aa7",
  • "request_for_payment_state": "REQUESTED",
  • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
  • "receiver_address": "trans_gbp_lon@rn.eur.uk.london",
  • "amount": 100.01,
  • "currency": "USD",
  • "quote_type": "SENDER_AMOUNT",
  • "end_to_end_id": "string",
  • "user_info": [
    • {
      • "node_address": "string",
      • "requested": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "accepted": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ],
      • "failed": [
        • {
          • "json": { },
          • "created_at": "2019-08-24T14:15:22Z",
          • "subState": "EXECUTING"
          }
        ]
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_id": "5492648d-2132-4e70-9ded-2fc86f22b321"
}
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.





Get transfers
Gets a list of transfers.


SecurityBearer 
Request 
query Parameters
page
integer
 Default:  0
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.


 
size
integer  [ 1 .. 100 ] 
 Default:  20
Number of objects to return per page.


 
with_labels
Array of strings
Returns transfers that contain any of the specified labels.
Example - ?with_labels=LABEL1,LABEL2


 
without_labels
Array of strings
Returns transfers that do not contain any of the specified labels.


 
include_labels
boolean
 Default:  false
Returns labels added to each Transfer object. By default labels are not returned. 
Example - ?with_labels=LABEL1&include_labels=true


 
state
string
Filter by transfer states.


 Enum: "PREPARED" "EXECUTED" "COMPLETED" "FAILED" "PENDING"  
internal_id
string
Optional parameter for filtering with internalId.


 
sender_end_to_end_id
string
Optional parameter for filtering with sender end to end id.


 
sort_field
string
Field used to sort the results.


 Enum: "CREATED_AT" "MODIFIED_AT"  
sort_direction
string
Sort direction.


 Enum: "ASC" "DESC"  
account
string
RippleNet account which is involved in transfer


 
transfer_account_role
string
by default account parameter would search both sender and receiver of transfer and bring the results. This is to restrict the account search to sender or receiver of a transfer


 Enum: "SENDING" "RECEIVING"  
Responses 
200
Successfully returned transfers.


400
Bad request.


get/transfers
Request samples 
Response samples 
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "size": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "sort": [
    • {
      • "direction": "ASC",
      • "property": "string",
      • "ignoreCase": true,
      • "nullHandling": "NULLS_FIRST",
      • "ascending": true,
      • "descending": false
      }
    ],
  • "content": [
    • {
      • "transfer_id": "9eca588f-e89d-4629-82fa-da9c4646310f",
      • "state": "EXECUTED",
      • "owner_address": "rn.us.ca.san_francisco",
      • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
      • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
      • "amount": 15,
      • "internal_id": "9cf5aa4b-1e44-436a-ab7c-d399aec905da",
      • "end_to_end_id": "fd7559be-aa85-433f-a283-0cd58681cdf0",
      • "sending_fee": 0,
      • "created_at": "2019-10-01T21:28:28.354Z",
      • "user_info": [
        • {
          • "node_address": "rn.us.ca.san_francisco",
          • "state": "EXECUTED",
          • "json": { },
          • "created_at": "2019-10-01T21:28:28.357Z"
          }
        ],
      • "labels": [
        • "label1",
        • "label2",
        • "label3"
        ]
      }
    ]
}
Get transfer estimate
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). This operation is only available to xCurrent instances enabled as receivers of xRapid payments.


SecurityBearer 
Request 
query Parameters
sender_address
string^[^\s]+@[^\s]+$
RippleNet address of the xRapid account from which the transfer is funded


 
receiver_address
string^[^\s]+@[^\s]+$
RippleNet address representing an account outside of RippleNet to which the transfer amount is sent.


 
amount
number  >= 0 
The amount to be transferred


 
Responses 
200
Successfully retrieved estimate of transfer sending fee


400
Bad request.


get/transfers/estimate
Request samples 
Response samples 
application/json
{
  • "transfer_id": "9eca588f-e89d-4629-82fa-da9c4646310f",
  • "state": "EXECUTED",
  • "owner_address": "rn.us.ca.san_francisco",
  • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
  • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
  • "amount": 15,
  • "internal_id": "9cf5aa4b-1e44-436a-ab7c-d399aec905da",
  • "end_to_end_id": "fd7559be-aa85-433f-a283-0cd58681cdf0",
  • "sending_fee": 0,
  • "created_at": "2019-10-01T21:28:28.354Z",
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "state": "EXECUTED",
      • "json": { },
      • "created_at": "2019-10-01T21:28:28.357Z"
      }
    ],
  • "labels": [
    • "label1",
    • "label2",
    • "label3"
    ]
}
Get transfer by ID
Gets a transfer by ID.


SecurityBearer 
Request 
path Parameters
transfer_id
required
string <uuid> 
Unique identifier of the transfer you want to retrieve.


 
query Parameters
include_labels
boolean
 Default:  false
Returns labels added to each Transfer object. By default labels are not returned.


 
Responses 
200
Successfully retrieved transfer.


404
Transfer not found.


get/transfers/{transfer_id}
Request samples 
Response samples 
application/json
{
  • "transfer_id": "9eca588f-e89d-4629-82fa-da9c4646310f",
  • "state": "EXECUTED",
  • "owner_address": "rn.us.ca.san_francisco",
  • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
  • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
  • "amount": 15,
  • "internal_id": "9cf5aa4b-1e44-436a-ab7c-d399aec905da",
  • "end_to_end_id": "fd7559be-aa85-433f-a283-0cd58681cdf0",
  • "sending_fee": 0,
  • "created_at": "2019-10-01T21:28:28.354Z",
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "state": "EXECUTED",
      • "json": { },
      • "created_at": "2019-10-01T21:28:28.357Z"
      }
    ],
  • "labels": [
    • "label1",
    • "label2",
    • "label3"
    ]
}
Execute transfer
Transfers funds between accounts. For example, use this request to fund a connector account by transferring funds from a transactional account to the connector account. You can also use this request to redeem funds to a transactional account by transferring funds from a connector account to the transactional account.


SecurityBearer 
Request 
Request Body schema: application/json
required
See Transfer Request Object.


sender_address
required
string
RippleNet account name and address, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.


 
receiver_address
required
string
RippleNet account name and address, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.


 
amount
required
number  >= 0 
Amount transferred, expressed in the account's currency.


 
owner_address
string
Owner RippleNet address, if different from the RippleNet address of the sender_address and receiver_address.


 
end_to_end_id
string  <= 128 characters 
ID set by the sender that is persisted on all xCurrent instances that participated in the transfer.


 
internal_id
string  <= 128 characters 
ID set by the sender that is persisted on the sending xCurrent instance only.


 
user_info
object
Provide one or more arbitrary key/value pairs.


 
Responses 
200
Successfully executed transfer.


400
Bad request.


post/transfers/execute
Request samples 
application/json
{
  • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
  • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
  • "amount": 15,
  • "owner_address": "rn.us.ca.san_francisco",
  • "end_to_end_id": "b09dd632-660e-48c8-907f-a4f3a7d12c18",
  • "internal_id": "9ad3c119-1379-443b-9c0e-fa82c54ae78d",
  • "user_info": { }
}
Response samples 
application/json
{
  • "transfer_id": "9eca588f-e89d-4629-82fa-da9c4646310f",
  • "state": "EXECUTED",
  • "owner_address": "rn.us.ca.san_francisco",
  • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
  • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
  • "amount": 15,
  • "internal_id": "9cf5aa4b-1e44-436a-ab7c-d399aec905da",
  • "end_to_end_id": "fd7559be-aa85-433f-a283-0cd58681cdf0",
  • "sending_fee": 0,
  • "created_at": "2019-10-01T21:28:28.354Z",
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "state": "EXECUTED",
      • "json": { },
      • "created_at": "2019-10-01T21:28:28.357Z"
      }
    ],
  • "labels": [
    • "label1",
    • "label2",
    • "label3"
    ]
}
Complete transfer
Updates the state of a transfer to COMPLETED. Make this request once the transfer has been made on both the ledger and on internal systems.


SecurityBearer 
Request 
path Parameters
transfer_id
required
string <uuid> 
Unique identifier of the transfer you want to complete.


 
Responses 
200
Successfully completed transfer.


404
Transfer not found.


post/transfers/{transfer_id}/complete
Request samples 
Response samples 
application/json
{
  • "transfer_id": "9eca588f-e89d-4629-82fa-da9c4646310f",
  • "state": "EXECUTED",
  • "owner_address": "rn.us.ca.san_francisco",
  • "sender_address": "trans_usd_sf@rn.us.ca.san_francisco",
  • "receiver_address": "conct_usd_sf@rn.us.ca.san_francisco",
  • "amount": 15,
  • "internal_id": "9cf5aa4b-1e44-436a-ab7c-d399aec905da",
  • "end_to_end_id": "fd7559be-aa85-433f-a283-0cd58681cdf0",
  • "sending_fee": 0,
  • "created_at": "2019-10-01T21:28:28.354Z",
  • "user_info": [
    • {
      • "node_address": "rn.us.ca.san_francisco",
      • "state": "EXECUTED",
      • "json": { },
      • "created_at": "2019-10-01T21:28:28.357Z"
      }
    ],
  • "labels": [
    • "label1",
    • "label2",
    • "label3"
    ]
}
Add transfer labels
Adds a list of labels to the transfer. To retrieve transfers by label, see [Get transfers][get-transfers].


SecurityBearer 
Request 
path Parameters
transfer_id
required
string <uuid> 
Transfer ID for the label being added.


 
query Parameters
label
required
Array of strings
Text of the label you want to add to the payment.


 
Responses 
200
Successfully added one or more labels to the transfer.


400
Bad request.


put/transfers/{transfer_id}/labels
Request samples 
Response samples 
application/json
{}
Delete transfer labels
Deletes one or more existing labels from the transfer.


SecurityBearer 
Request 
path Parameters
transfer_id
required
string <uuid> 
Transfer ID for the label being removed.


 
query Parameters
label
required
Array of strings
Labels to be removed.


 
Responses 
200
Successfully deleted one or more labels of the transfer.


400
Bad request.


delete/transfers/{transfer_id}/labels
Request samples 
Response samples 
application/json
{}