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.


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


For the recommended format, see Working with the piiData object.


 
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 Individual Beneficiary",
  • "useCaseType": "INDIVIDUAL",
  • "piiData": {
    • "Cdtr": {
      • "StrdNm": {
        • "FirstNm": "Dana",
        • "LastNm": "Doe"
        },
      • "CtctDtls": {
        • "MobNb": "+1234567890",
        • "EmailAdr": "test@test.com"
        },
      • "CtryOfRes": "GB",
      • "Id": {
        • "PrvtId": {
          • "Othr": {
            • "Id": "1234567890",
            • "SchmeNm": {
              • "Cd": "CUST"
              }
            },
          • "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 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"
}
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 payout on behalf of your customer


 
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.




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