Payments Direct API ( )

Use the Ripple Payments Direct API to get quotes, create and manage payments, and manage originator 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}.rnc.ripplenet.com/v4

Base URL

The base URL for the Ripple Payments Direct API follows the {domainprefix}.{domain} pattern. For the test environment, the {domainprefix} is {customername}.test. For the production environment, the {domainprefix} is {customername}.

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 Direct API.

https://{domainprefix}.{domain}/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.rnc ripplenet.com https://aperture.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
BENEFICIARY

Identity associated with the beneficiary.

ORIGINATOR

Identity associated with the party originating the payment.

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",
      • "identityType": "BENEFICIARY",
      • "useCaseType": "BUSINESS"
      }
    ]
}

Create a new identity

Create a new identity.

Tutorials

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

Create a new business or institutional beneficiary identity.

required
object (pii-data-business-beneficiary)

PII data for a business or institutional benficiary in JSON format.

The specific properties you need to specify within the Cdtr, CdtrAgt, and CdtrAcct objects depend on the type of payment you plan to make to this beneficiary and the payout country and currency. To get the required properties for your use case, call the GET /data-requirements operation. For more information about the piiData object, see Working with the piiData object.

Note: The piiData.Cdtr.Id.OrgId.Othr.Id value must be unique for every identity you create in your account.

identityType
required
string (identity-type)

The type of the identity

Enum: Description
BENEFICIARY

Identity associated with the beneficiary.

ORIGINATOR

Identity associated with the party originating the payment.

nickName
string

The nickname for the new identity.

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

useCaseType
required
string (useCaseType)

The use case type for the identity

Enum: Description
INDIVIDUAL

Identity associated with an individual

BUSINESS

Identity associated with an institution or business

Responses
201

successful operation

400

Invalid Request

500

Internal Processing Error

post/identities
Request samples
application/json
{
  • "identityType": "BENEFICIARY",
  • "nickName": "Successful Business Beneficiary",
  • "useCaseType": "BUSINESS",
  • "piiData": {
    • "Cdtr": {
      • "Nm": "Success Co.",
      • "CtctDtls": {
        • "MobNb": "+1234567890",
        • "EmailAdr": "test@test.com"
        },
      • "CtryOfRes": "AT",
      • "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
BENEFICIARY

Identity associated with the beneficiary.

ORIGINATOR

Identity associated with the party originating the payment.

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 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 [ 1 .. 100000000 ]

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"
}

Data requirements

Use this API operation to get the data required for making a payout using a specific currency.

Operation Method Description
Get data requirements GET Retrieve data requirements.

Get data requirements

Returns the fields required to make a payout using the given payout method.

SecurityBearer
Request
query Parameters
payout-country
required
string

The beneficiary's country in ISO 3166-1 alpha-2 code format.

Example: payout-country=AU
use-case
required
string

The use case for the payment.

Enum: Description
B2B

A business pays another business

B2C

A business pays an individual

B2B2B

A business pays another business on behalf of a business

B2B2C

A business pays an individual on behalf of a business

payout-currency
required
string

The beneficiary's account currency in ISO-4217 alpha-3 code format.

Example: payout-currency=EUR
payout-category
required
string

The payout category for the payment. This field corresponds to payoutMethodName in the 200 response.

Value: "BANK"
Example: payout-category=BANK
partner-name
required
string

The name of Ripple's payout partner. Please reach out to your Ripple liasion to get the value.

field-category
required
string

Field category specifies the type of party involved in the transaction.

Field category Description
ORIGINATOR The identity corresponds to a payment originator
BENEFICIARY The identity corresponds to a payment beneficiary
Example: field-category=BENEFICIARY
flow
required
string

The only supported value is RPD.

Example: flow=RPD
Responses
200

Returns all the data requirements for the payout method identified by its id

Response Schema: application/json
supportedUseCase
required
string

The use case for the payment.

payoutCountry
required
string

The beneficiary's country in ISO 3166-1 alpha-2 code format.

payoutCurrency
required
string

The beneficiary's account currency in ISO-4217 alpha-3 code format.

payoutMethodName
string

The payout method determined using the provided data.

required
Array of objects (DataRequirement)
401

Response when authentication of the request fails

403

Response when the principal identified by the authorization header doesn't have enough scopes to perform this operation

404

Resource not found

500

Internal server error

get/data-requirements
Request samples
Response samples
application/json
{
  • "dataRequirements": [
    • {
      • "fieldCategory": "ORIGINATOR",
      • "fieldName": "Dbtr.Nm",
      • "fieldType": "REQUIRED",
      • "fieldDataType": "STRING",
      • "fieldMinLength": 2,
      • "fieldMaxLength": 100,
      • "fieldDescription": "Originator Name - Corporate",
      • "fieldHelpText": "The legal name of the originator business"
      },
    • {
      • "fieldCategory": "BENEFICIARY",
      • "fieldName": "CdtrAgt.FinInstnId.Nm",
      • "fieldType": "REQUIRED",
      • "fieldDataType": "STRING",
      • "fieldMinLength": 0,
      • "fieldMaxLength": 50,
      • "fieldDescription": "Beneficiary's Bank name.",
      • "fieldHelpText": "Name by which the party is known and which is usually used to identify the party."
      }
    ],
  • "payoutCountry": "AU",
  • "payoutCurrency": "EUR",
  • "payoutMethodName": "sepa",
  • "supportedUseCase": "B2B"
}

Reports

Use these API operations to get payment reports.

Operation Method Description
List reports GET Returns an array of reports available for download.
Create a report POST Create a report.
Get a report GET Get the download link for a specific report.
Delete a report DELETE Delete 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 reportId, reportType, and reportFormat fields associated with that report.

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

SecurityBearer
Request
query Parameters
created-by
string (CreatedByEnum)

Query for report types based on the entity that initiated report creation.

Value Description
SCHEDULER Get automated system-generated reports.
USER Customized reports generated by users through the UI.
API Customized reports generated using the API.
Enum: "USER" "SCHEDULER" "API"
Example: created-by=USER
Responses
200

Returns an array of report metadata for the calling tenant

Response Schema: application/json
required
Array of objects (ReportMetadata) >= 0 items
400

Bad Report Request

403

Forbidden

get/v1/reports
Request samples
Response samples
application/json
{
  • "reports": [
    • {
      • "reportId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "reportName": "My custom report",
      • "reportType": "PAYMENT_OPS",
      • "reportFormat": "CSV",
      • "reportStatus": "READY",
      • "startDate": "2018-04-06T20:33:35Z",
      • "endDate": "2018-04-06T20:33:35Z",
      • "createdOn": "2018-04-06T20:33:35Z",
      • "reportCreatedBy": "Norma Jean"
      }
    ]
}

Create report

Request the generation of a custom report based on the specified parameters.

Report duration

Reports can contain up to 90 days of transactions from the previous 9 months.

  • Minimum report duration is 1 day.
  • Maximum report duration is 90 days.

Report retention

Reports are retained for 6 months after the endDate specified in your request. After this period, the report is purged and will no longer be accessible.

SecurityBearer
Request
Request Body schema: application/json

Parameters defining the requested report

reportName
required
string (report_name) [ 1 .. 256 ] characters

User defined name of the report.

startDate
required
string <date-time>

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

endDate
required
string <date-time>

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

Note: Must be after startDate, but no more than 90 days after.

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

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

Responses
200

Returns the JSON record for the posted report

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

Unique identifier for a report.

reportName
string (report_name) [ 1 .. 256 ] characters

User defined name of the report.

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

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

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

startDate
required
string <date-time>

The ISO-8601 start date (inclusive) of the report.

endDate
required
string <date-time>

The ISO-8601 end date (inclusive) of the report.

Note: Must be after startDate, but no more than 90 days after.

createdOn
string <date-time> (report_created_on)

Report creation time

400

Bad Report Request

403

Forbidden

post/v1/reports
Request samples
application/json
{
  • "reportName": "My custom report",
  • "startDate": "2018-04-06T19:33:35Z",
  • "endDate": "2018-04-06T20:33:35Z",
  • "reportType": "PAYMENT_OPS",
  • "reportFormat": "CSV"
}
Response samples
application/json
{
  • "reportId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "reportName": "My custom report",
  • "reportType": "PAYMENT_OPS",
  • "reportFormat": "CSV",
  • "reportStatus": "READY",
  • "startDate": "2018-04-06T19:33:35Z",
  • "endDate": "2018-04-06T20:33:35Z",
  • "createdOn": "2018-04-06T20:33:35Z"
}

Get a report

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

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

SecurityBearer
Request
path Parameters
report-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
reportId
required
string <uuid>

Unique identifier for a report.

reportName
string (report_name) [ 1 .. 256 ] characters

User defined name of the report.

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

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

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

startDate
required
string <date-time>

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

endDate
required
string <date-time>

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

Note: Must be after startDate, but no more than 90 days after.

createdOn
string <date-time> (report_created_on)

Report creation time

downloadLink
string <uri> [ 1 .. 2048 ] characters

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

reportCreatedBy
string (ReportCreatedBy) [ 1 .. 128 ] characters

Identifies the entity that initiated the report creation.

Value Description
SCHEDULER Automated system-generated report initiated by the scheduler.
API User-generated report initiated through the API.
[full name] Full name of the user who initiated the creation of the report through the UI.
null Legacy support for older reports.
400

Bad request

403

Forbidden

404

Not found

get/v1/reports/{report-id}
Request samples
Response samples
application/json
{}

Delete reports

Delete a specific report with the report-id path parameter.

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

Unique ID for a report

Responses
204

The resource was successfully deleted.

404

Reports not found

500

Error while attempting to delete resource

delete/v1/reports/{report-id}
Request samples

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
report-id
required
string <uuid>

Unique identifier for a report. Get this report-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) [ 1 .. 128 ] characters

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

ripplenet_payment_id
string (ripplenet_payment_id) [ 1 .. 128 ] characters

The 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) [ 1 .. 128 ] characters

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

sender_customer
string (sender_customer) [ 1 .. 128 ] characters

The name of the sending institution.

sent_amount
number (sent_amount)

The payment amount sent.

sent_currency
string (sent_currency) [ 1 .. 128 ] characters

The ISO 4217 currency code of the of sent_amount.

receiver_address
string (receiver_address) [ 1 .. 128 ] characters

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

receiver_customer
string (receiver_customer) [ 1 .. 128 ] characters

Name of the receiving institution.

received_amount
number (received_amount)

The payment amount received by the beneficiary.

received_currency
string (received_currency) [ 1 .. 128 ] characters

The ISO 4217 currency code of the received_amount.

payment_method
string (payment_method) [ 1 .. 128 ] characters

[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) [ 1 .. 128 ] characters

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

remitter_name
string (remitter_name) [ 1 .. 128 ] characters

Complete name of the person originating the payment.

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

remitter_account
string (remitter_account) [ 1 .. 128 ] characters

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) [ 1 .. 128 ] characters

Complete name of the person receiving the payment.

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

beneficiary_account
string (beneficiary_account) [ 1 .. 128 ] characters

Account number at the receiving institution for the payment beneficiary.

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

payment_batch_id
string (payment_batch_id) [ 1 .. 36 ] characters

Unique identifier for a batch of payments.

Note: This field is only populated for payments that are part of a batch.

204

The contents of the report are empty

400

Bad request

403

Forbidden

404

Not found

get/v1/reports/download/{report-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",
  • "payment_batch_id": "497f6eca-1234-5678-bfeb-53cbbbba6f08"
}