Payments Direct API ( )

Use the Ripple Payments Direct API to get quotes, create and manage payments, and manage sender and beneficiary identities.

API environments

The Ripple Payments Direct API offers the following environments:

Environment
Base URL
Test https://{customer-name}.test.rnc.ripplenet.com/v4
Production https://{customer-name}.prod.rnc.ripplenet.com/v4

Base URL

The base URL for the Ripple Payments Direct API follows the {customername}.{environment}.{domain} pattern.

Note: The following examples use aperture as the customer name, your customer name will be different.

URL format

This is the URL format for the Ripple Payments DirectAPI.

https://{customername}.{environment}/v4

Example base URL

This is an example base URL for the Ripple Payments Direct API.

https://aperture.test.rnc.ripplenet.com/v4/{path}?{parameters}

Example fully-qualified URL

This connects to the test environment and requests a list of payments with 100 results per page.

https://aperture.test.rnc.ripplenet.com/v4/payments?page=0&size=100
Environment
Domain Prefix
Domain Base URL
Test aperture.test rnc.ripplenet.com https://aperture.test.rnc.ripplenet.com/v4
Production aperture.prod rnc.ripplenet.com https://aperture.prod.rnc.ripplenet.com/v4

API authentication

All Ripple Payments Direct API operations require a Bearer access token specific to the environment you're using. Ripple provides a secure model for authentication and authorization by providing access tokens scoped for a set of credentials.

Generate client ID and client secret

You will need your client ID and client secret to obtain an access token.

If you do not already have your client ID and client secret, do the following:

  1. Log into the Ripple Payments UI.
  2. In the left navigation menu, click Settings.
  3. Under Administration, click API Credentials.
  4. In the dropdown list next to the page title, select the access environment. For example, to provision credentials for the test environment, select Test from the dropdown list.
  5. In the upper right corner of the page, click New Credential.
  6. Click Save and Generate Key.

Caution: The client secret is displayed only once when you are creating new credentials. You cannot retrieve the secret after exiting this page. Copy and store the client secret securely and share it with authorized individuals in accordance with your organization's security policy.

You can now use the client ID and client secret to generate access tokens using the Request an access token operation.

Request an access token

To get an access token, use the Request an access token operation with your client_id and client_secret. The response contains a token in the access_token field.

We recommend rotating your API credentials at regular intervals according to your organization's security policy.

Note: Authentication tokens are not a fixed length and can vary, avoid validating tokens based on character length.

Authentication

Use these API operations to manage your authentication tokens.

Operation Method Description
Request an access token POST Request an access token for authentication with Ripple APIs.
Test access token GET Test if an access token can be used for authentication.

Request an access token

Request an access token for authentication with Ripple APIs.

You need to request a token for the environment you want to authenticate with.

Note: The length of the access token isn't fixed, hence it can vary. Avoid validating tokens based on character length.

Environments

Environment Domain Description
Test auth-test.rnc.ripplenet.com Test environment with simulated partners and simulated currency.
Production auth.rnc.ripplenet.com Production environment for Ripple's internal services.
SecurityBasicAuth
Request
header Parameters
Authorization
string

Optional base64-encoded client_id:client_secret.

If provided here they aren't required in the request body.

Example: Basic ZGVtbzpwQDU1dzByZA==
Request Body schema:
client_id
required
string

The client ID associated with a specific set of API credentials.

See API authentication for instructions obtaining your client ID.

client_secret
required
string

The client secret associated with a specific set of API credentials.

See API authentication for instructions obtaining your client secret.

audience
required
string

The value of the audience field is based on URN syntax.

Format: urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}

  • The first component is urn:ripplenetxcurrent-.
  • The second component refers to the environment you want to access.
  • The third component is your tenant ID. Ripple integration engineers provide this component during training.
Environment Environment string Description
Test test Test environment with simulated partners and simulated currency.
Production prod Production environment for Ripple's internal services.

Example: urn:ripplexcurrent-prod:{YOUR_TENANT_ID}

grant_type
required
string

Set the grant-type for this client credentials request. This must be set to client_credentials.

Value: "client_credentials"
Responses
200

Returns the authentication response object that includes the token, type, scopes, and expiry.

Response Schema: application/json
access_token
string

The bearer token you use when authenticating with a Ripple API.

scope
string

List of scopes applied to your access_token.

expires_in
integer <int64>

How long your access_token is valid. You need to request a new token when it expires.

token_type
string

The type of token. Ripple APIs use Bearer auth tokens.

400

Bad Request

401

Unauthorized

403

Forbidden

post/oauth/token
Request samples
{
  • "client_id": "{YOUR_CLIENT_ID}",
  • "client_secret": "{YOUR_CLIENT_SECRET}",
  • "audience": "urn:ripplexcurrent-prod:{YOUR_TENANT_ID}",
  • "grant_type": "client_credentials"
}
Response samples
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
  • "scope": "identities:create identities:read identities:write quote_collections:write payments:accept payments:read routing_table:lookup",
  • "expires_in": 3600,
  • "token_type": "Bearer"
}

Test access token

Test if an access token can be used for authentication with Ripple APIs and how much time remains on it.

SecurityBearer
Responses
200

If a valid access token is supplied, the time remaining before the token expires is returned.

Response Schema: application/json
Array
message
string

Success message

seconds_to_expiry
integer <int64>

Remaining time in seconds before the tested token expires.

400

Bad Request

401

Unauthorized

get/oauth/token/test
Request samples
Response samples
application/json
[
  • {
    • "message": "token_ok",
    • "seconds_to_expiry": 3600
    }
]

Identities

Use these API operations to manage your identities.

Operation Method Description
List identities GET Get a list of existing identities.
Create an identity POST Create a new identity.
Get an identity by ID GET Get an identity by its unique ID.
Delete an identity DELETE Delete an identity.

Get a list of identities

Get a list of identities that match the query parameters.

Note: Depending on the number of identities in your account, not all of them may be returned even if they match your query parameters.

SecurityBearer
Request
query Parameters
identityType
string (identity-type)

The type of identities you want to retrieve

Enum: Description
SENDER

Identity associated with the sender.

BENEFICIARY

Identity associated with the beneficiary.

Example: identityType=BENEFICIARY
nickName
string

The nickname of the identity provided at the time of identity creation.

Example: nickName=Successful Beneficiary
Responses
200

Requested identity info in JSON format

Response Schema: application/json
Array of objects (identity)

The list of the identities that match the query parameters

400

Invalid request

404

No identities found

500

Internal Processing Error

get/identities
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
      • "nickName": "MyCompany",
      • "createdAt": "2023-11-02T18:26:00.000Z"
      }
    ]
}

Create a new identity

Create a new identity.

Tutorials

SecurityBearer
Request
Request Body schema: application/json
One of:

Create a new beneficiary identity.

required
object (pii-data-beneficiary)

Example piiData object for beneficiaries.

See Working with the piiData object.

identityType
required
string (identity-type)

The type of the identity

Enum: Description
SENDER

Identity associated with the sender.

BENEFICIARY

Identity associated with the beneficiary.

nickName
string

The nickname for the new identity.

Note: Don't include any personally identifiable information in this field.

Responses
201

successful operation

400

Invalid Request

500

Internal Processing Error

post/identities
Request samples
application/json
{
  • "identityType": "BENEFICIARY",
  • "nickName": "Successful Beneficiary",
  • "piiData": {
    • "Cdtr": {
      • "Nm": "Success Co.",
      • "CtctDtls": {
        • "MobNb": "+1234567890",
        • "EmailAdr": "test@test.com"
        },
      • "CtryOfRes": "GB",
      • "Id": {
        • "OrgId": {
          • "Othr": {
            • "Id": "1234567890",
            • "SchmeNm": {
              • "Cd": "CINC"
              }
            },
          • "RelShipToDbtr": "CUST"
          }
        },
      • "PstlAdr": {
        • "AdrLine": [
          • "1234 Beneficiary Ave"
          ],
        • "PstCd": "02125",
        • "TwnNm": "Boston"
        }
      },
    • "CdtrAcct": {
      • "Ccy": "US",
      • "Id": {
        • "IBAN": "1234123412341234",
        • "Othr": {
          • "SchmeNm": {
            • "Cd": "BBAN"
            }
          }
        }
      },
    • "CdtrAgt": {
      • "BrnchId": {
        • "PstlAdr": {
          • "Ctry": "US"
          }
        },
      • "FinInstnId": {
        • "Nm": "Bank of Massachusetts",
        • "Othr": {
          • "Id": "123456"
          }
        }
      }
    }
}
Response samples
application/json
{
  • "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  • "version": 2
}

Get an identity by ID

Get an identity by its unique ID

SecurityBearer
Request
path Parameters
identity-id
required
string <uuid>

The ID of the identity to get.

Example: 2f4ac57f-c5ba-4051-b51f-b3565778717b
query Parameters
version
integer >= 1

Version of the identity you want to retrieve.

Note: If you don't specify a version, the latest version of the identity is returned.

Example: version=2
Responses
200

Requested identity info in JSON format

Response Schema: application/json
identityId
required
string

The unique ID of the identity

identityType
required
string (identity-type)

The type of the identity

Enum: Description
SENDER

Identity associated with the sender.

BENEFICIARY

Identity associated with the beneficiary.

createdAt
required
string <date-time>

The time at which the identity was created

identityState
required
string (state-type)

The state of the identity

Enum: Description
ACTIVE

The identity requested exists and is active.

BLOCKED

The identity requested exists, but is blocked.

DELETED

The identity requested has been deleted.

nickName
string

The nickname of the identity provided at the time of identity creation.

required
object

PII data in JSON format

version
required
integer

The version number of the identity

400

Identity ID is not in UUID format

404

Invalid - identity ID does not exist

422

Identity ID is an invalid UUID string

get/identities/{identity-id}
Request samples
Response samples
application/json
{
  • "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  • "identityType": "BENEFICIARY",
  • "createdAt": "2023-11-02T18:26:00.000Z",
  • "identityState": "ACTIVE",
  • "nickName": "MyCompany",
  • "piiData": { },
  • "version": 2
}

Delete an identity

Delete an identity

SecurityBearer
Request
path Parameters
identity-id
required
string

Unique UUID string that maps to the identity to be deleted.

Example: 2f4ac57f-c5ba-4051-b51f-b3565778717b
Responses
204

The identity was deleted successfully

400

Identity id is not of UUID format

404

Invalid Identity id does not exist

422

Unprocessable Identity Id

500

Internal Processing Error

delete/identities/{identity-id}
Request samples
Response samples
application/json
{
  • "code": "400",
  • "category": "CLIENT_ERROR",
  • "title": "Bad Request",
  • "detail": "Invalid request. Check your request parameters and try again.",
  • "retryable": true
}

Payments

Use these API operations to manage your payments.

Operation Method Description
Get payments GET Get a list of existing payments.
Get payment by payment ID GET Get a specific payment by payment ID.

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

Optional parameter to filter results based on the sending_currency_code.

receiving_currency
string

Optional parameter to filter results based on the receiving_currency_code.

internal_id
string

Optional parameter to filter results based on the internal_id.

sender_end_to_end_id
string

Optional parameter to filter results based on the sender_end_to_end_id.

states
Array of strings

Returns payments in the specified states.

State Description
ACCEPTED The sender has made a successful Accept quote request and a payment ID was created.
PREPARED An automatic Settle payment request was made and the crypto-transaction created.
PROCESSING_COMPLIANCE The payment request is going through Ripple's compliance process.
EXECUTED The funds have been transferred to the receiver account.
COMPLETED The funds have reached the end beneficiary.
FAILED The payment has been actively stopped by a participating institution or the payment has failed automatically because it expired.
Example: states=ACCEPTED,EXECUTED
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: Required if you 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: Required if you specify range_field.

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

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
ACCEPTED_AT Filter by quote accepted date-time
EXECUTED_AT Filter by executed date-time
COMPLETED_AT Filter by completed date-time
EXPIRES_AT Filter by quote expiry 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.

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

Value Description
SENDING_AMOUNT The amount range to filter payments on is applied to the sending amount
RECEIVING_AMOUNT The amount range to filter payments on is applied to the receiving amount.

Dependency: Required when minAmount and/or maxAmount is 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.

sort_field
string
Default: "MODIFIED_AT"

Sorts results according to the specified field.

Sort field Description
PAYMENT_ID TBD
EXPIRES_AT Sort by quote expiry date-time
MODIFIED_AT Sort by modified date-time
CREATED_AT Sort by creation date-time
Enum: "PAYMENT_ID" "EXPIRES_AT" "MODIFIED_AT" "CREATED_AT"
sort_direction
string
Default: "DESC"

Sorts result according to the specified direction.

Sort direction Description
ASC Sort ascending
DESC Sort descending
payment_ids
Array of strings <uuid>

List of paymentIds to search for

Responses
200

Successful response

Response Schema:
first
boolean

True if this is the first page.

last
boolean

True if this is the last page.

number
integer

Page number.

numberOfElements
integer

Number of elements in this request.

size
integer

Page size.

totalElements
integer <int64>

Total number of elements for the given request.

totalPages
integer

Total number of pages for the given request.

Array of objects (Sort)

Sort details of this page.

Array of objects (Payment)
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": "2024-03-22T15:24:19.587Z",
        • "expires_at": "2024-05-21T15:13:31.275Z",
        • "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": "DIRECT",
      • "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": "string",
            • "counter_currency_code": "string",
            • "type": "string"
            },
          • "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": "string",
            • "counter_currency_code": "string",
            • "type": "string"
            },
          • "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": "string",
            • "counter_currency_code": "string",
            • "type": "string"
            },
          • "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",
      • "executed_at": "2019-10-01T18:25:47.347Z",
      • "completed_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.

Response Schema: application/json
payment_id
required
string <uuid>

Unique identifier of a payment.

contract_hash
required
string

Hash of all values in the Contract object used to ensure immutability. The values in this object cannot change once a payment transitions into the PROCESSING_COMPLIANCE state.

payment_state
required
string

State of the payment.

Enum: Description
ACCEPTED

The sender has made a successful Accept quote request and a payment ID was created.

PROCESSING_COMPLIANCE

The payment request is going through Ripple's compliance process.

PREPARED

An automatic Settle payment request was made and the crypto-transaction created.

EXECUTED

The funds have been transferred to the receiver account.

COMPLETED

The funds have reached the end beneficiary.

FAILED

The payment has been actively stopped by a participating institution or the payment has failed automatically because it expired.

modified_at
required
string <date-time>

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

required
object (PaymentContract)

Represents all immutable parts of a payment agreed upon by all participants as a part of the payment compliance processing flow. The values in this object cannot change once a payment transitions to the PROCESSING_COMPLIANCE state.

Array of objects (RippleNetInfo)

Application-provided data explaining actions taken by RippleNet applications.

execution_condition
required
string

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

crypto_transaction_id
required
string

Unique identifier of the crypto transaction associated with this payment.

validator
required
string

Address of the validator that validated the payment.

payment_type
required
string

Payment type.

Value: "DIRECT"
required
Array of objects (ExecutionResult)

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

Array of objects (ExecutionResult)

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

object (LiquidationDetails)

Payment liquidation details

Array of objects (ExecutionResult)

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

accepted_at
required
string <date-time>

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

executed_at
string <date-time>

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

completed_at
string <date-time>

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

required
object (InternalInfo)

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

required
Array of objects (UserInfo)

User-provided data with arbitrary key/value pairs.

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": "2024-03-22T15:24:19.587Z",
    • "expires_at": "2024-05-21T15:13:31.275Z",
    • "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": "string",
            • "counter_currency_code": "string",
            • "type": "string"
            },
          • "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": "DIRECT",
  • "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": "string",
        • "counter_currency_code": "string",
        • "type": "string"
        },
      • "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": "string",
        • "counter_currency_code": "string",
        • "type": "string"
        },
      • "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": "string",
        • "counter_currency_code": "string",
        • "type": "string"
        },
      • "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",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_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"
          }
        ]
      }
    ]
}

Quotes

Use these API operations to manage your quotes.

Operation Method Description
Accept quote POST Accepts a quote ID to start the payment process.
Create quote collection POST Create a collection of quotes.

Accept quote

Accepts a quote ID to start the payment process.

Tutorials

SecurityBearer
Request
Request Body schema: application/json

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

Sender-specified ID.

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
required
object

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

Responses
200

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

Response Schema: application/json
payment_id
required
string <uuid>

Unique identifier of a payment.

contract_hash
required
string

Hash of all values in the Contract object used to ensure immutability. The values in this object cannot change once a payment transitions into the PROCESSING_COMPLIANCE state.

payment_state
required
string

State of the payment.

Enum: Description
ACCEPTED

The sender has made a successful Accept quote request and a payment ID was created.

PROCESSING_COMPLIANCE

The payment request is going through Ripple's compliance process.

PREPARED

An automatic Settle payment request was made and the crypto-transaction created.

EXECUTED

The funds have been transferred to the receiver account.

COMPLETED

The funds have reached the end beneficiary.

FAILED

The payment has been actively stopped by a participating institution or the payment has failed automatically because it expired.

modified_at
required
string <date-time>

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

required
object (PaymentContract)

Represents all immutable parts of a payment agreed upon by all participants as a part of the payment compliance processing flow. The values in this object cannot change once a payment transitions to the PROCESSING_COMPLIANCE state.

Array of objects (RippleNetInfo)

Application-provided data explaining actions taken by RippleNet applications.

execution_condition
required
string

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

crypto_transaction_id
required
string

Unique identifier of the crypto transaction associated with this payment.

validator
required
string

Address of the validator that validated the payment.

payment_type
required
string

Payment type.

Value: "DIRECT"
required
Array of objects (ExecutionResult)

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

Array of objects (ExecutionResult)

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

object (LiquidationDetails)

Payment liquidation details

Array of objects (ExecutionResult)

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

accepted_at
required
string <date-time>

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

executed_at
string <date-time>

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

completed_at
string <date-time>

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

required
object (InternalInfo)

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

required
Array of objects (UserInfo)

User-provided data with arbitrary key/value pairs.

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": "2024-03-22T15:24:19.587Z",
    • "expires_at": "2024-05-21T15:13:31.275Z",
    • "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": "string",
            • "counter_currency_code": "string",
            • "type": "string"
            },
          • "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": "DIRECT",
  • "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": "string",
        • "counter_currency_code": "string",
        • "type": "string"
        },
      • "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": "string",
        • "counter_currency_code": "string",
        • "type": "string"
        },
      • "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": "string",
        • "counter_currency_code": "string",
        • "type": "string"
        },
      • "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",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_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"
          }
        ]
      }
    ]
}

Create quote collection

Creates a collection of quotes for a proposed payment.

Prerequisite

Tutorials

SecurityBearer
Request
Request Body schema: application/json
sending_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.

receiving_address
required
string

Account name of the receiving institution.

amount
required
number >= 0

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

Use this table to determine what currency code to assign.

Example: USD

Quote type Currency code
SENDER_AMOUNT Sending currency
SENDER_INSTITUTION_AMOUNT Sending currency
RECEIVER_AMOUNT Receiving currency
RECEIVER_INSTITUTION_AMOUNT Receiving currency
quote_type
required
string

Specifies how to calculate the quote.

Example: SENDER_AMOUNT

Enum: Description
SENDER_AMOUNT

Quote based on the amount the payment originator or originating institution wants to send

RECEIVER_AMOUNT

Quote based on the amount the payment beneficiary or beneficiary institution should receive

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

Example: USD

payment_method
string

Payout method for the quote.

Note: The value must match the value of payout_method field in the response from the Get payout method operation.

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

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
Items Enum: Description
LIQUIDITY_WARNINGS

Filter for liquidity warnings

QUOTE_ERRORS

Filter for quote errors

Responses
200

Successfully returned quote collection.

Response Schema: application/json
quote_collection_id
required
string <uuid>

Unique identifier of the quote collection.

required
Array of objects (Quote)
Array of objects (QuoteError)
400

Bad request.

post/quote_collections
Request samples
application/json
{
  • "sending_address": "sf@rn.us.ca.san_francisco",
  • "receiving_address": "rn.sgp.tranglo",
  • "amount": 1,
  • "currency": "USD",
  • "quote_type": "SENDER_AMOUNT",
  • "sender_or_receiver_currency": "USD",
  • "payment_method": "string",
  • "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": "string",
            • "counter_currency_code": "string",
            • "type": "string"
            },
          • "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"
      }
    ]
}

Routing

Use this API operation to look up a payout method.

Operation Method Description
Get payout method GET Look up a payout method.

Get payout method

Look up the payout method based on the beneficiary's country.

Tutorial

SecurityBearer
Request
query Parameters
country_code
required
string

The ISO 3166-1 alpha-2 country code of the country in which the payment beneficiary is located.

Example: country_code=DE
payout_currency_code
string

The ISO 4217 Currency Code of the currency in which the beneficiary will be paid out.

Example: payout_currency_code=EUR
payment_method
required
string

The payment method used to pay out the beneficiary. BANK_PAYOUT is the only payment method currently supported.

Value: "BANK_PAYOUT"
global
required
boolean

Use global lookup table. This must be set to true.

Responses
200

Destination lookup completed successfully

Response Schema: application/json
id
string <uuid>

The ID of the routing table entry that matches the parameter values specified in the request.

destination_address
string

The destination RippleNet address.

payout_method
string

The payout method based on the payout country and currency.

Note: Use the value of this field as the value for the payment_method parameter in the Create a quote collection operation.

get/config/routing_table/lookup
Request samples
Response samples
application/json
{
  • "id": "235b9711-cf8c-44ea-85aa-11dbbfcfde8b",
  • "destination_address": "rn.sgp.tranglo",
  • "payout_method": "CSM_EU_EUR_SEPA"
}

Reports

Use these API operations to get payment reports.

Operation Method Description
List reports GET Returns an array of reports available for download.
Get a report GET Get the download link for a specific report.
Download a report GET Download a transaction report.

List reports

Returns an array of reports available for download. Each array element represents an available report, and contains the id, type, and format fields associated with that report.

To get the download link for a specific report, store the id for the report you want, and use it with the Get a report operation.

SecurityBearer
Responses
200

Returns an array of report metadata for the calling tenant

Response Schema: application/json
required
Array of objects (ReportRecord)
400

Bad Report Request

403

Forbidden

404

Not found

get/reports
Request samples
Response samples
application/json
{
  • "reports": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "type": "PAYMENT_OPS",
      • "format": "CSV",
      • "status": "READY",
      • "start_date": "2018-04-06T20:33:35Z",
      • "end_date": "2018-04-06T20:33:35Z"
      }
    ]
}

Get a report

Here, you apply the id from the List reports operation as the path parameter to get a download_link containing the report.

Download the report at the link in the download_link field in the response.

SecurityBearer
Request
path Parameters
id
required
string <uuid>

Unique identifier for a report.

Example: 497f6eca-6276-4993-bfeb-53cbbbba6f08
Responses
200

Returns the JSON record of the report specified in the path parameter

Response Schema: application/json
id
required
string <uuid>

Unique identifier for a report.

type
required
string (ReportTypeEnum)

The report type of the downloadable report.

Value: Description
PAYMENT_OPS

Basic payment report suitable for high-level payment investigation and reporting.

format
required
string (ReportFormatEnum)

The report format of the downloadable report.

Enum: Description
CSV

A CSV file is a text file that uses a comma to delimit values. Each line of text corresponds to a unique record.

JSON

JSON (Javascript Object Notation) is a file format that uses human-readable text to store and transmit data objects consisting of attribute-value pairs and arrays.

status
required
string (ReportStatusEnum)

The status of the report.

Enum: Description
PENDING

Report isn't ready for download.

READY

Report is ready for download.

FAILED

Unable generate the report.

EMPTY

Report has no transactions for the date range.

start_date
required
string <date-time>

The ISO-8601 start date (inclusive) for a requested report.

end_date
required
string <date-time>

The ISO-8601 end date (inclusive) for a requested report.

Note: Must be after start_date, but no more than 31 days after.

download_link
string <uri>

Link where you can download the report in the available format. This field is available when the report status is READY.

400

Bad request

403

Forbidden

404

Not found

get/reports/{id}
Request samples
Response samples
application/json
{}

Download a report

Download a transaction report. Download the report by applying the report id from the List reports operation as a path parameter.

SecurityBearer
Request
path Parameters
id
required
string <uuid>

Unique identifier for a report. Get this id from the List reports operation.

Example: 497f6eca-6276-4993-bfeb-53cbbbba6f08
Responses
200

Returns the JSON record of the report specified in the path parameter.

Response Schema: application/json
end_to_end_id
string (end_to_end_id)

Unique ID that the sender specifies. It persists on all RippleNet instances that participate in the payment.

ripplenet_payment_id
string (ripplenet_payment_id)

Unique payment identifier.

quote_ts
string <date-time>

The ISO-8601 timestamp of the quote.

created_at
string <date-time>

The ISO-8601 timestamp when the transaction was created.

executed_at
string <date-time>

The ISO-8601 timestamp when the payment was settled.

sender_address
string (sender_address)

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress.

sender_customer
string (sender_customer)

Name of the sending institution.

sent_amount
number (sent_amount)

The payment amount sent.

sent_currency
string (sent_currency)

The ISO 4217 currency code of the of sent_amount.

receiver_address
string (receiver_address)

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress.

receiver_customer
string (receiver_customer)

Name of the receiving institution.

received_amount
number (received_amount)

The payment amount received by the beneficiary.

received_currency
string (received_currency)

The ISO 4217 currency code of the received_amount.

payment_method
string (payment_method)

[Sender only]

Method for completing the payment. This is a freeform text field that accepts custom strings for payment methods, for example:

  • CSM_ID_IDR
  • MSISDN_ID_IDR
  • CASHPICKUP_ID_IDR
  • CARD_CN_CNY

Or you can use RippleNet payment method values:

  • REAL_TIME_GROSS_SETTLEMENT_SYSTEM
  • REAL_TIME_NET_SETTLEMENT_SYSTEM
  • MASS_NET_PAYMENT_SYSTEM
  • BOOK_TRANSFER
  • CASH_PAYOUT
  • WALLET_PAYMENT
  • OTHER
payment_state
string (payment_state)

The state of a payment at the moment it is queried.

remitter_name
string (remitter_name)

Complete name of the person originating the payment.

Note: Values are only viewable by the customer requesting the report.

remitter_account
string (remitter_account)

Account number at the sending institution for the payment remitter.

Note: Values are only viewable by the customer requesting the report.

beneficiary_name
string (beneficiary_name)

Complete name of the person receiving the payment.

Note: Values are only viewable by the customer requesting the report.

beneficiary_account
string (beneficiary_account)

Account number at the receiving institution for the payment beneficiary.

Note: Values are only viewable by the customer requesting the report.

204

The contents of the report are empty

400

Bad request

403

Forbidden

404

Not found

get/reports/download/{id}
Request samples
Response samples
application/json
{
  • "end_to_end_id": "string",
  • "ripplenet_payment_id": "70eccd4f-abcd-1234-a655-3aeddff19e4a",
  • "quote_ts": "2019-08-24T14:15:22Z",
  • "created_at": "2022-10-02T20:57:13.606Z",
  • "executed_at": "2022-10-02T20:57:20.62Z",
  • "sender_address": "new_york@rn.us.ny.new_york",
  • "sender_customer": "examplecorp_sf",
  • "sent_amount": 40,
  • "sent_currency": "USD",
  • "receiver_address": "new_york@rn.us.ny.new_york",
  • "receiver_customer": "sf",
  • "received_amount": 39.45,
  • "received_currency": "PHP",
  • "payment_method": "CSM_TH_THB",
  • "payment_state": "COMPLETED",
  • "remitter_name": "string",
  • "remitter_account": "string",
  • "beneficiary_name": "string",
  • "beneficiary_account": "string"
}