Payments Direct 1.0 API ( )

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

API environments

The Ripple Payments Direct 1.0 API offers the following environments:

<div style="width:90px">Environment</div>	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 1.0 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 1.0 API.

https://{domainprefix}.{domain}/v4

Example base URL

This is an example base URL for the Ripple Payments Direct 1.0 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	<div style="width:120px;">Domain Prefix</div>	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 1.0 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:

Log into the Ripple Payments UI.
In the left navigation menu, click Settings.
Under Administration, click API Credentials.
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.
In the upper right corner of the page, click New Credential.
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.

Servers

Mock server

https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-swagger/reference/payments-direct-swagger-external/

Development environment

https://{{customer-name}}.test.rnc.ripplenet.com/v4/

Production environment

https://{{customer-name}}.rnc.ripplenet.com/v4/

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.

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.

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.

Operations

Get payments

Request

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'

Security

Bearer

Query

pageinteger

The page number for paginated results.

The value is zero-based, where 0 represents the first page. Set it to 0 to get the first page of results.

Default 0

sizeinteger[ 1 .. 100 ]

Number of payments to return per page.

Default 10

sending_currencystring

Optional parameter to filter results based on the sending_currency_code.

receiving_currencystring

Optional parameter to filter results based on the receiving_currency_code.

internal_idstring

Optional parameter to filter results based on the internal_id.

sender_end_to_end_idstring

Optional parameter to filter results based on the sender_end_to_end_id.

statesArray 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

beforestring

Before time stamp

Filters for payments where the range_field column value is before this specified time stamp (inclusive).

You can also specify after to create a time range between after and before.

Dependency: Required if you specify range_field.

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

afterstring

After time stamp

Filters for payments where the range_field column value is after this specified time stamp (inclusive).

You can also specify before to create a time range between after and before.

Dependency: Required if you specify range_field.

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

range_fieldstring

Range field

Designates the column name of the payments database table that is used for filtering payments before/after/between time stamps.

The following options are valid:

Range field	Description
CREATED_AT	Filter by created date-time
MODIFIED_AT	Filter by modified date-time
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_fieldstring

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_amountnumber>= 0

Optional parameter for filtering with min sending/receiving amount.

max_amountnumber>= 0

Optional parameter for filtering with max sending/receiving amount.

sort_fieldstring

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

Default "MODIFIED_AT"

Enum"PAYMENT_ID""EXPIRES_AT""MODIFIED_AT""CREATED_AT"

sort_directionstring

Sorts result according to the specified direction.

Sort direction	Description
ASC	Sort ascending
DESC	Sort descending

Default "DESC"

payment_idsArray of strings(uuid)

List of paymentIds to search for

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-swagger/reference/payments-direct-swagger-external/payments?page=0&size=10&sending_currency=string&receiving_currency=string&internal_id=string&sender_end_to_end_id=string&states=ACCEPTED%2CEXECUTED&before=string&after=string&range_field=string&amount_range_field=SENDING_AMOUNT&min_amount=0&max_amount=0&sort_field=PAYMENT_ID&sort_direction=DESC&payment_ids=497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Body

firstboolean

True if this is the first page.

lastboolean

True if this is the last page.

numberinteger

Page number.

numberOfElementsinteger

Number of elements in this request.

sizeinteger

Page size.

totalElementsinteger(int64)

Total number of elements for the given request.

totalPagesinteger

Total number of pages for the given request.

sortArray of objects

Sort details of this page.

directionstring

Direction of the sort

Example: "ASC"

propertystring

ignoreCaseboolean

nullHandlingstring

Example: "NULLS_FIRST"

ascendingboolean

Example: true

descendingboolean

Example: false

contentArray of objects

payment_idstring(uuid)required

Unique identifier of a payment.

Example: "d485f100-2af7-4e48-9ab1-3c7e28775691"

contract_hashstringrequired

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.

Example: "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103"

payment_statestringrequired

State of the payment.

Enum Value	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.

Example: "COMPLETED"

modified_atstring(date-time)required

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

Example: "2019-10-01T18:25:47.347Z"

contractobjectrequired

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.

sender_end_to_end_idstring[ 1 .. 128 ] charactersrequired

ID that the sender can specify. Persisted on all RippleNet instances that participate in the payment.

created_atstring(date-time)required

Date and time at which this payment contract was created, as an ISO-8601 timestamp in UTC.

Example: "2024-03-22T15:24:19.587Z"

expires_atstring(date-time)required

Date and time after which this payment contract expires, as an ISO-8601 timestamp in UTC.

Default "300s/300000ms"

Example: "2024-05-21T15:13:31.275Z"

quoteobjectrequired

JSON response object that represents a quote for a proposed payment or return payment.

quote_idstring(uuid)required

Unique identifier for the quote.

Example: "2a547e56-4aac-4375-86a8-8b3e7014801d"

created_atstring(date-time)required

Date and time at which the quote was created, as an ISO-8601 timestamp in UTC.

Example: "2020-01-29T20:59:44.925Z"

expires_atstring(date-time)required

Date and time after which the quote and its pricing expire.

Default "300s/300000ms"

Example: "2020-01-29T21:29:44.925Z"

typestringrequired

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

Enum"SENDER_AMOUNT""RECEIVER_AMOUNT""SENDER_INSTITUTION_AMOUNT""RECEIVER_INSTITUTION_AMOUNT""REVERSAL_AMOUNT"

Example: "SENDER_AMOUNT"

price_guaranteestringrequired

Indicates whether a quote's pricing is INDICATIVE or FIRM. An INDICATIVE quote allows for price movements between quote issuance and payment execution, such that the quoted amount and delivered amount may differ. A FIRM quote ensures that the quoted and delivered payment amounts are equal.

Default "FIRM"

Example: "FIRM"

sender_addressstringrequired

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

Example: "sf@rn.us.ca.san_francisco"

receiver_addressstringrequired

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

Example: "sf_gbp@rn.us.ca.san_francisco"

amountnumberrequired

Amount to be sent or received, depending on the type value.

Example: 1

currency_codestringrequired

Currency code for the amount value.

Example: "USD"

currency_code_filterstringrequired

Currency code that can be used to filter quotes at the opposite end of the quote request. For example, you can filter by this currency code to find the receiving currency for a quote with a SENDER_AMOUNT quote_type. If not sent in the request, this field value is set to null.

Example: "EUR"

service_typestringrequired

Returns null.

quote_elementsArray of objectsrequired

Transfer and exchange elements. A transfer element represents a movement of funds between two accounts. An exchange element represents the exchange of currencies between two accounts.

liquidity_warningstringrequired

Triggered when a quote causes an account to go below its minimum_allowed_balance. Otherwise, this field value is set to null.

payment_methodstring

Payout method for the quote.

Example: "LOCAL_RAILS"

payment_method_fieldsstring

JSON object containing payment method metadata.

Example: "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}"

payout_method_infoobject

Details about the payout method.

fee_infoobject

Itemized list of fees charged by each node.

nodesobjectrequired

Fees charged by each node participating in the payment.

total_feesArray of objectsrequired

Total fees charged in the payment, separated by currency.

ripplenet_infoArray of objects

Application-provided data explaining actions taken by RippleNet applications.

node_addressstringrequired

RippleNet address of the node from which the RippleNetInfo originated.

Example: "rn.us.ny.new_york"

settlement_declinedArray of objectsrequired

If applicable, provides an array of RippleNetInfoEntry's explaining transitions into the SETTLEMENT_DECLINED state

infostring

Information explaining the action taken by a RippleNet application. Could be a RippleNet error code, or a written explanation of the action taken

Example: "L001"

created_atstring(date-time)

The DateTime that this quote was created, as an ISO-8601 timestamp in UTC.

Example: "2018-04-06T20:33:35Z"

execution_conditionstringrequired

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.

Example: "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}"

crypto_transaction_idstringrequired

Unique identifier of the crypto transaction associated with this payment.

Example: "4e05da26-7872-4a1f-b9b7-db7604757c37"

validatorstringrequired

Address of the validator that validated the payment.

Example: "rn.us.ca.san_francisco"

payment_typestringrequired

Payment type.

Value"DIRECT"

Example: "DIRECT"

execution_resultsArray of objectsrequired

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

execution_result_idstring(uuid)required

Unique identifier for this payment result.

Example: "06f6d4e2-3523-4d17-92fd-53192a06207f"

execution_timestampstring(date-time)required

Date and time at which this portion of the payment was executed.

Example: "2019-10-01T18:24:29.867Z"

execution_result_typestringrequired

Type of payment execution result.<p><ul> <li>TRANSFER represents the movement of funds between two accounts.</li> <li>EXCHANGE represents the exchange of currencies between two accounts.</li> <li>EXCHANGE_TRADE represents the exchange of fiat to digital currency on a digital exchange.</li> <li>CRYPTO_TRANSFER represents the movement of digital funds between two digital exchanges.</li> </ul></p>

Enum"TRANSFER""EXCHANGE""EXCHANGE_TRADE""CRYPTO_TRANSFER"

Example: "TRANSFER"

execution_result_orderintegerrequired

Order in which the payment execution action was taken along the liquidity path. For example, a payment may include five execution results along the liquidity path. Each execution result has an order number that indicates the order in which the execution result was achieved to make the payment.

Example: 1

sender_addressstringrequired

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

Example: "trans_usd_sf@rn.us.ca.san_francisco"

receiver_addressstringrequired

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

Example: "conct_usd_sf@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 498

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 498

sending_feenumberrequired

Fees the sender is charging.

Example: 2

receiving_feenumberrequired

Fees the receiver is charging.

Example: 0

sending_currency_codestring

Currency code of the sending amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "USD"

receiving_currency_codestring

Currency of the receiving amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "GBP"

fx_rateobject

The details of an FX Rate for a quote or payment.

ratenumberrequired

Exchange rate between a base and counter currency.

Example: 3.25

base_currency_codestringrequired

Currency code of the base currency.

counter_currency_codestringrequired

Currency code of the counter currency.

typestringrequired

Order type of the exchange rate. Valid values are buy or sell.

transfer_currency_codestring

Currency of the transfer. Returned in execution results with execute_result_type set to TRANSFER.

intermediary_deltanumber

Amount of XRP representing the difference in FX rate between the moment of quoting and the moment of execution. A positive value is the amount taken out of the incentive pool. A negative value is the amount returned to the incentive pool. (Soon to be deprecated)

Example: 0.2

incentive_typestring

Configuration of the incentive pool on the xRapid side. Two values are supported, firm and fx. For firm, xRapid guarantees that the FX rate at the moment of execution is the same as at the moment of quoting. For fx, xRapid guaratees a predefined FX rate.

Example: "firm"

incentive_valuenumber

Example: 0.2

transaction_hashstring

Hash representing the unique identifier for the transfer of funds in the XRP ledger.

Example: 5.5467794184785867e+76

venue_idstring

The id from an exchange associated with a transaction involving an exchange account.

Example: "nz7RpAujYgnQtjEM"

fiat_adjusted_valuenumber

Represents the delta between quoted and received executed amounts, for exchange trades.

Example: 0.02

odl_payment_idstring

Payment ID in On-Demand Liquidity (ODL) for an executed ODL payment containing the transaction represented by this execution result.

liquidation_execution_resultsArray of objects

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

execution_result_idstring(uuid)required

Unique identifier for this payment result.

Example: "06f6d4e2-3523-4d17-92fd-53192a06207f"

execution_timestampstring(date-time)required

Date and time at which this portion of the payment was executed.

Example: "2019-10-01T18:24:29.867Z"

execution_result_typestringrequired

Enum"TRANSFER""EXCHANGE""EXCHANGE_TRADE""CRYPTO_TRANSFER"

Example: "TRANSFER"

execution_result_orderintegerrequired

Example: 1

sender_addressstringrequired

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

Example: "trans_usd_sf@rn.us.ca.san_francisco"

receiver_addressstringrequired

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

Example: "conct_usd_sf@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 498

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 498

sending_feenumberrequired

Fees the sender is charging.

Example: 2

receiving_feenumberrequired

Fees the receiver is charging.

Example: 0

sending_currency_codestring

Currency code of the sending amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "USD"

receiving_currency_codestring

Currency of the receiving amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "GBP"

fx_rateobject

The details of an FX Rate for a quote or payment.

ratenumberrequired

Exchange rate between a base and counter currency.

Example: 3.25

base_currency_codestringrequired

Currency code of the base currency.

counter_currency_codestringrequired

Currency code of the counter currency.

typestringrequired

Order type of the exchange rate. Valid values are buy or sell.

transfer_currency_codestring

Currency of the transfer. Returned in execution results with execute_result_type set to TRANSFER.

intermediary_deltanumber

Example: 0.2

incentive_typestring

Example: "firm"

incentive_valuenumber

Example: 0.2

transaction_hashstring

Hash representing the unique identifier for the transfer of funds in the XRP ledger.

Example: 5.5467794184785867e+76

venue_idstring

The id from an exchange associated with a transaction involving an exchange account.

Example: "nz7RpAujYgnQtjEM"

fiat_adjusted_valuenumber

Represents the delta between quoted and received executed amounts, for exchange trades.

Example: 0.02

odl_payment_idstring

Payment ID in On-Demand Liquidity (ODL) for an executed ODL payment containing the transaction represented by this execution result.

liquidation_detailsobject

Payment liquidation details

idstring(uuid)

Liquidation ID, unique to the liquidation process of this payment

statusstring

Liquidation status

failure_reasonstring

Reason behind failure of the liquidation, only applicable if the status is failure

failure_countinteger

Number of times the liquidation failed. Irrelevant if status is successful.

push_forward_execution_resultsArray of objects

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

execution_result_idstring(uuid)required

Unique identifier for this payment result.

Example: "06f6d4e2-3523-4d17-92fd-53192a06207f"

execution_timestampstring(date-time)required

Date and time at which this portion of the payment was executed.

Example: "2019-10-01T18:24:29.867Z"

execution_result_typestringrequired

Enum"TRANSFER""EXCHANGE""EXCHANGE_TRADE""CRYPTO_TRANSFER"

Example: "TRANSFER"

execution_result_orderintegerrequired

Example: 1

sender_addressstringrequired

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

Example: "trans_usd_sf@rn.us.ca.san_francisco"

receiver_addressstringrequired

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

Example: "conct_usd_sf@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 498

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 498

sending_feenumberrequired

Fees the sender is charging.

Example: 2

receiving_feenumberrequired

Fees the receiver is charging.

Example: 0

sending_currency_codestring

Currency code of the sending amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "USD"

receiving_currency_codestring

Currency of the receiving amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "GBP"

fx_rateobject

The details of an FX Rate for a quote or payment.

ratenumberrequired

Exchange rate between a base and counter currency.

Example: 3.25

base_currency_codestringrequired

Currency code of the base currency.

counter_currency_codestringrequired

Currency code of the counter currency.

typestringrequired

Order type of the exchange rate. Valid values are buy or sell.

transfer_currency_codestring

Currency of the transfer. Returned in execution results with execute_result_type set to TRANSFER.

intermediary_deltanumber

Example: 0.2

incentive_typestring

Example: "firm"

incentive_valuenumber

Example: 0.2

transaction_hashstring

Hash representing the unique identifier for the transfer of funds in the XRP ledger.

Example: 5.5467794184785867e+76

venue_idstring

The id from an exchange associated with a transaction involving an exchange account.

Example: "nz7RpAujYgnQtjEM"

fiat_adjusted_valuenumber

Represents the delta between quoted and received executed amounts, for exchange trades.

Example: 0.02

odl_payment_idstring

Payment ID in On-Demand Liquidity (ODL) for an executed ODL payment containing the transaction represented by this execution result.

accepted_atstring(date-time)required

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

Example: "2019-10-01T18:25:47.347Z"

executed_atstring(date-time)

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

Example: "2019-10-01T18:25:47.347Z"

completed_atstring(date-time)

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

Example: "2019-10-01T18:25:47.347Z"

internal_infoobjectrequired

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.

connector_rolestringrequired

Role of the RippleNet node that sets one or more values in the Internal Info object.

Use as follows:

SENDING: Sending account in the payment resides on this RippleNet instance.
RECEIVING: Receiving account in the payment resides on this RippleNet instance.
INTERMEDIARY: Neither sending nor receiving accounts in the payment reside on this RippleNet instance.
INTERNAL: Both sending and receiving accounts in the payment (usually between RippleNet Cloud and RippleNet) reside on this RippleNet instance.

Enum"SENDING""RECEIVING""INTERMEDIARY""INTERNAL"

Example: "RECEIVING"

labelsArray of objectsrequired

Array of objects that provide label values that are set by including the sub_state field at any stage of the payment's lifecycle. Labels can be used as a filtering mechanism when searching for payments. Labels are visible only to the node that added them to this copy of a payment. If the values that populate this array are not set in the request or if the values set in the request are not viewable by your node, this array is empty.

labelstring

Label to be attached

internal_idstringrequired

ID that is viewable only to the node that set it. This value can be set by the sender when accepting a payment. This value can also be set by any intermediary and the receiver when locking the payment. If this value is not set in the request or if the value set in the request is not viewable by your node, this field value is set to null.

user_infoArray of objectsrequired

User-provided data with arbitrary key/value pairs.

node_addressstringrequired

RippleNet address of the node that provided the user information.

Example: "rn.us.ca.san_francisco"

acceptedArray of objectsrequired

User information optionally provided when accepting the payment.

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

lockedArray of objectsrequired

User information optionally provided when locking the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

lock_declinedArray of objectsrequired

User information optionally provided when declining to lock the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

retry_acceptArray of objectsrequired

User information optionally provided when retrying acceptance of the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

retry_settlementArray of objectsrequired

User information optionally provided when retrying settlement of the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

settlementArray of objectsrequired

User information optionally provided when settling the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

settlement_declinedArray of objectsrequired

User information optionally provided when settlement for the payment is declined. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

failedArray of objectsrequired

User information optionally provided when failing the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

executedArray of objectsrequired

Payment sub-state information provided using sub_state and memo fields when finalizing the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

completedArray of objectsrequired

User information optionally provided when completing the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

forwardedArray of objectsrequired

If applicable, user information optionally provided when forwarding the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

returnedArray of objectsrequired

If applicable, information optionally provided using return_reasons when returning the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

Response

{
  "first": true,
  "last": true,
  "number": 0,
  "numberOfElements": 0,
  "size": 0,
  "totalElements": 0,
  "totalPages": 0,
  "sort": [
    { … }
  ],
  "content": [
    { … }
  ]
}

Get payment by payment ID

Request

Gets a payment by ID.

Security

Bearer

Path

payment_idstring(uuid)required

Unique identifier of the payment you want to retrieve.

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-swagger/reference/payments-direct-swagger-external/payments/{payment_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successfully retrieved payment.

Bodyapplication/json

payment_idstring(uuid)required

Unique identifier of a payment.

Example: "d485f100-2af7-4e48-9ab1-3c7e28775691"

contract_hashstringrequired

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.

Example: "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103"

payment_statestringrequired

State of the payment.

Enum Value	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.

Example: "COMPLETED"

modified_atstring(date-time)required

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

Example: "2019-10-01T18:25:47.347Z"

contractobjectrequired

sender_end_to_end_idstring[ 1 .. 128 ] charactersrequired

ID that the sender can specify. Persisted on all RippleNet instances that participate in the payment.

created_atstring(date-time)required

Date and time at which this payment contract was created, as an ISO-8601 timestamp in UTC.

Example: "2024-03-22T15:24:19.587Z"

expires_atstring(date-time)required

Date and time after which this payment contract expires, as an ISO-8601 timestamp in UTC.

Default "300s/300000ms"

Example: "2024-05-21T15:13:31.275Z"

quoteobjectrequired

JSON response object that represents a quote for a proposed payment or return payment.

quote_idstring(uuid)required

Unique identifier for the quote.

Example: "2a547e56-4aac-4375-86a8-8b3e7014801d"

created_atstring(date-time)required

Date and time at which the quote was created, as an ISO-8601 timestamp in UTC.

Example: "2020-01-29T20:59:44.925Z"

expires_atstring(date-time)required

Date and time after which the quote and its pricing expire.

Default "300s/300000ms"

Example: "2020-01-29T21:29:44.925Z"

typestringrequired

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

Enum"SENDER_AMOUNT""RECEIVER_AMOUNT""SENDER_INSTITUTION_AMOUNT""RECEIVER_INSTITUTION_AMOUNT""REVERSAL_AMOUNT"

Example: "SENDER_AMOUNT"

price_guaranteestringrequired

Default "FIRM"

Example: "FIRM"

sender_addressstringrequired

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

Example: "sf@rn.us.ca.san_francisco"

receiver_addressstringrequired

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

Example: "sf_gbp@rn.us.ca.san_francisco"

amountnumberrequired

Amount to be sent or received, depending on the type value.

Example: 1

currency_codestringrequired

Currency code for the amount value.

Example: "USD"

currency_code_filterstringrequired

Example: "EUR"

service_typestringrequired

Returns null.

quote_elementsArray of objectsrequired

Transfer and exchange elements. A transfer element represents a movement of funds between two accounts. An exchange element represents the exchange of currencies between two accounts.

quote_element_idstring(uuid)required

Unique identifier for the quote element.

Example: "259189e7-cb14-42e7-99ef-375f3285e356"

quote_element_typestringrequired

Type of quote element.<p><ul> <li>TRANSFER represents the movement of funds between two accounts.</li> <li>EXCHANGE represents the exchange of currencies between two accounts.</li> <li>EXCHANGE_TRADE represents the exchange of fiat to digital currency on a digital exchange.</li> <li>CRYPTO_TRANSFER represents the movement of digital funds between two digital exchanges.</li> </ul></p>

Enum"TRANSFER""EXCHANGE""EXCHANGE_TRADE""CRYPTO_TRANSFER"

Example: "EXCHANGE"

quote_element_orderintegerrequired

Order of each quote element along the liquidity path. If a quote includes five quote elements, each one is enacted according to its quote_element_order number to make the proposed payment.

Example: 1

sender_addressstringrequired

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

Example: "sf@rn.us.ca.san_francisco"

receiver_addressstringrequired

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

Example: "sf_gbp@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 1

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 355

sending_feenumberrequired

Fees the sender is charging. When quote_element_type is set to EXCHANGE, this field value is always set to 0.

Example: 0

receiving_feenumberrequired

Fees the receiver is charging. When quote_element_type is set to EXCHANGE, this field value is always set to 0.

Example: 0

sending_currency_codestring

Currency code of the sending amount. Included in quote elements with quote_element_type set to EXCHANGE.

Example: "USD"

receiving_currency_codestring

Currency code of the receiving amount. Included in quote elements with quote_element_type set to EXCHANGE.

Example: "GBP"

fx_rateobject

The details of an FX Rate for a quote or payment.

transfer_currency_codestring

Currency code of the transfer. Included in quote elements with quote_element_type set to TRANSFER.

liquidity_warningstringrequired

Triggered when a quote causes an account to go below its minimum_allowed_balance. Otherwise, this field value is set to null.

payment_methodstring

Payout method for the quote.

Example: "LOCAL_RAILS"

payment_method_fieldsstring

JSON object containing payment method metadata.

Example: "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}"

payout_method_infoobject

Details about the payout method.

payout_method_namestring

Payout method for the quote.

Example: "Cash Payout"

payout_method_categorystring

Category of the payout method. Defaults to <code>OTHER</code> if not specified.

Enum"REAL_TIME_GROSS_SETTLEMENT_SYSTEM""REAL_TIME_NET_SETTLEMENT_SYSTEM""MASS_NET_PAYMENT_SYSTEM""BOOK_TRANSFER""CASH_PAYOUT""WALLET_PAYMENT""OTHER"

Example: "BOOK_TRANSFER"

descriptionstring

User defined description of the payout method.

Example: "local rails"

estimated_time_to_creditstring

The estimated time to credit the beneficiary using this payout method.

Example: "3 days"

fee_infoobject

Itemized list of fees charged by each node.

nodesobjectrequired

Fees charged by each node participating in the payment.

property name*Array of objectsadditional property

total_feesArray of objectsrequired

Total fees charged in the payment, separated by currency.

total_feenumberrequired

Value of the total fee for the currency returned in fee_currency.

fee_currencystringrequired

ISO 4217 currency code of the currency the total fee applies to.

ripplenet_infoArray of objects

Application-provided data explaining actions taken by RippleNet applications.

node_addressstringrequired

RippleNet address of the node from which the RippleNetInfo originated.

Example: "rn.us.ny.new_york"

settlement_declinedArray of objectsrequired

If applicable, provides an array of RippleNetInfoEntry's explaining transitions into the SETTLEMENT_DECLINED state

infostring

Information explaining the action taken by a RippleNet application. Could be a RippleNet error code, or a written explanation of the action taken

Example: "L001"

created_atstring(date-time)

The DateTime that this quote was created, as an ISO-8601 timestamp in UTC.

Example: "2018-04-06T20:33:35Z"

execution_conditionstringrequired

Example: "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}"

crypto_transaction_idstringrequired

Unique identifier of the crypto transaction associated with this payment.

Example: "4e05da26-7872-4a1f-b9b7-db7604757c37"

validatorstringrequired

Address of the validator that validated the payment.

Example: "rn.us.ca.san_francisco"

payment_typestringrequired

Payment type.

Value"DIRECT"

Example: "DIRECT"

execution_resultsArray of objectsrequired

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

execution_result_idstring(uuid)required

Unique identifier for this payment result.

Example: "06f6d4e2-3523-4d17-92fd-53192a06207f"

execution_timestampstring(date-time)required

Date and time at which this portion of the payment was executed.

Example: "2019-10-01T18:24:29.867Z"

execution_result_typestringrequired

Enum"TRANSFER""EXCHANGE""EXCHANGE_TRADE""CRYPTO_TRANSFER"

Example: "TRANSFER"

execution_result_orderintegerrequired

Example: 1

sender_addressstringrequired

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

Example: "trans_usd_sf@rn.us.ca.san_francisco"

receiver_addressstringrequired

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

Example: "conct_usd_sf@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 498

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 498

sending_feenumberrequired

Fees the sender is charging.

Example: 2

receiving_feenumberrequired

Fees the receiver is charging.

Example: 0

sending_currency_codestring

Currency code of the sending amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "USD"

receiving_currency_codestring

Currency of the receiving amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "GBP"

fx_rateobject

The details of an FX Rate for a quote or payment.

ratenumberrequired

Exchange rate between a base and counter currency.

Example: 3.25

base_currency_codestringrequired

Currency code of the base currency.

counter_currency_codestringrequired

Currency code of the counter currency.

typestringrequired

Order type of the exchange rate. Valid values are buy or sell.

transfer_currency_codestring

Currency of the transfer. Returned in execution results with execute_result_type set to TRANSFER.

intermediary_deltanumber

Example: 0.2

incentive_typestring

Example: "firm"

incentive_valuenumber

Example: 0.2

transaction_hashstring

Hash representing the unique identifier for the transfer of funds in the XRP ledger.

Example: 5.5467794184785867e+76

venue_idstring

The id from an exchange associated with a transaction involving an exchange account.

Example: "nz7RpAujYgnQtjEM"

fiat_adjusted_valuenumber

Represents the delta between quoted and received executed amounts, for exchange trades.

Example: 0.02

odl_payment_idstring

Payment ID in On-Demand Liquidity (ODL) for an executed ODL payment containing the transaction represented by this execution result.

liquidation_execution_resultsArray of objects

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

execution_result_idstring(uuid)required

Unique identifier for this payment result.

Example: "06f6d4e2-3523-4d17-92fd-53192a06207f"

execution_timestampstring(date-time)required

Date and time at which this portion of the payment was executed.

Example: "2019-10-01T18:24:29.867Z"

execution_result_typestringrequired

Enum"TRANSFER""EXCHANGE""EXCHANGE_TRADE""CRYPTO_TRANSFER"

Example: "TRANSFER"

execution_result_orderintegerrequired

Example: 1

sender_addressstringrequired

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

Example: "trans_usd_sf@rn.us.ca.san_francisco"

receiver_addressstringrequired

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

Example: "conct_usd_sf@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 498

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 498

sending_feenumberrequired

Fees the sender is charging.

Example: 2

receiving_feenumberrequired

Fees the receiver is charging.

Example: 0

sending_currency_codestring

Currency code of the sending amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "USD"

receiving_currency_codestring

Currency of the receiving amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "GBP"

fx_rateobject

The details of an FX Rate for a quote or payment.

ratenumberrequired

Exchange rate between a base and counter currency.

Example: 3.25

base_currency_codestringrequired

Currency code of the base currency.

counter_currency_codestringrequired

Currency code of the counter currency.

typestringrequired

Order type of the exchange rate. Valid values are buy or sell.

transfer_currency_codestring

Currency of the transfer. Returned in execution results with execute_result_type set to TRANSFER.

intermediary_deltanumber

Example: 0.2

incentive_typestring

Example: "firm"

incentive_valuenumber

Example: 0.2

transaction_hashstring

Hash representing the unique identifier for the transfer of funds in the XRP ledger.

Example: 5.5467794184785867e+76

venue_idstring

The id from an exchange associated with a transaction involving an exchange account.

Example: "nz7RpAujYgnQtjEM"

fiat_adjusted_valuenumber

Represents the delta between quoted and received executed amounts, for exchange trades.

Example: 0.02

odl_payment_idstring

Payment ID in On-Demand Liquidity (ODL) for an executed ODL payment containing the transaction represented by this execution result.

liquidation_detailsobject

Payment liquidation details

idstring(uuid)

Liquidation ID, unique to the liquidation process of this payment

statusstring

Liquidation status

failure_reasonstring

Reason behind failure of the liquidation, only applicable if the status is failure

failure_countinteger

Number of times the liquidation failed. Irrelevant if status is successful.

push_forward_execution_resultsArray of objects

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

execution_result_idstring(uuid)required

Unique identifier for this payment result.

Example: "06f6d4e2-3523-4d17-92fd-53192a06207f"

execution_timestampstring(date-time)required

Date and time at which this portion of the payment was executed.

Example: "2019-10-01T18:24:29.867Z"

execution_result_typestringrequired

Enum"TRANSFER""EXCHANGE""EXCHANGE_TRADE""CRYPTO_TRANSFER"

Example: "TRANSFER"

execution_result_orderintegerrequired

Example: 1

sender_addressstringrequired

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

Example: "trans_usd_sf@rn.us.ca.san_francisco"

receiver_addressstringrequired

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

Example: "conct_usd_sf@rn.us.ca.san_francisco"

sending_amountnumberrequired

Amount the sender is sending.

Example: 498

receiving_amountnumberrequired

Amount the receiver is receiving.

Example: 498

sending_feenumberrequired

Fees the sender is charging.

Example: 2

receiving_feenumberrequired

Fees the receiver is charging.

Example: 0

sending_currency_codestring

Currency code of the sending amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "USD"

receiving_currency_codestring

Currency of the receiving amount. Included in execution results with execution_result_type set to EXCHANGE.

Example: "GBP"

fx_rateobject

The details of an FX Rate for a quote or payment.

ratenumberrequired

Exchange rate between a base and counter currency.

Example: 3.25

base_currency_codestringrequired

Currency code of the base currency.

counter_currency_codestringrequired

Currency code of the counter currency.

typestringrequired

Order type of the exchange rate. Valid values are buy or sell.

transfer_currency_codestring

Currency of the transfer. Returned in execution results with execute_result_type set to TRANSFER.

intermediary_deltanumber

Example: 0.2

incentive_typestring

Example: "firm"

incentive_valuenumber

Example: 0.2

transaction_hashstring

Hash representing the unique identifier for the transfer of funds in the XRP ledger.

Example: 5.5467794184785867e+76

venue_idstring

The id from an exchange associated with a transaction involving an exchange account.

Example: "nz7RpAujYgnQtjEM"

fiat_adjusted_valuenumber

Represents the delta between quoted and received executed amounts, for exchange trades.

Example: 0.02

odl_payment_idstring

Payment ID in On-Demand Liquidity (ODL) for an executed ODL payment containing the transaction represented by this execution result.

accepted_atstring(date-time)required

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

Example: "2019-10-01T18:25:47.347Z"

executed_atstring(date-time)

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

Example: "2019-10-01T18:25:47.347Z"

completed_atstring(date-time)

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

Example: "2019-10-01T18:25:47.347Z"

internal_infoobjectrequired

connector_rolestringrequired

Role of the RippleNet node that sets one or more values in the Internal Info object.

Use as follows:

SENDING: Sending account in the payment resides on this RippleNet instance.
RECEIVING: Receiving account in the payment resides on this RippleNet instance.
INTERMEDIARY: Neither sending nor receiving accounts in the payment reside on this RippleNet instance.
INTERNAL: Both sending and receiving accounts in the payment (usually between RippleNet Cloud and RippleNet) reside on this RippleNet instance.

Enum"SENDING""RECEIVING""INTERMEDIARY""INTERNAL"

Example: "RECEIVING"

labelsArray of objectsrequired

labelstring

Label to be attached

internal_idstringrequired

user_infoArray of objectsrequired

User-provided data with arbitrary key/value pairs.

node_addressstringrequired

RippleNet address of the node that provided the user information.

Example: "rn.us.ca.san_francisco"

acceptedArray of objectsrequired

User information optionally provided when accepting the payment.

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

lockedArray of objectsrequired

User information optionally provided when locking the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

lock_declinedArray of objectsrequired

User information optionally provided when declining to lock the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

retry_acceptArray of objectsrequired

User information optionally provided when retrying acceptance of the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

retry_settlementArray of objectsrequired

User information optionally provided when retrying settlement of the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

settlementArray of objectsrequired

User information optionally provided when settling the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

settlement_declinedArray of objectsrequired

User information optionally provided when settlement for the payment is declined. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

failedArray of objectsrequired

User information optionally provided when failing the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

executedArray of objectsrequired

Payment sub-state information provided using sub_state and memo fields when finalizing the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

completedArray of objectsrequired

User information optionally provided when completing the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

forwardedArray of objectsrequired

If applicable, user information optionally provided when forwarding the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

returnedArray of objectsrequired

If applicable, information optionally provided using return_reasons when returning the payment. For more information, see [User Info Entry Object][user-info-entry].

jsonobjectrequired

User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

created_atstring(date-time)required

Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

subStatestring

If provided, this parameter descibes payment state more granularly.

Example: "EXECUTING"

Response

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": { … },
    "fee_info": { … }
  },
  "ripplenet_info": [
    { … }
  ],
  "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": [
    { … }
  ],
  "liquidation_execution_results": [
    { … }
  ],
  "liquidation_details": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "string",
    "failure_reason": "string",
    "failure_count": 0
  },
  "push_forward_execution_results": [
    { … }
  ],
  "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": [ … ],
    "internal_id": "string"
  },
  "user_info": [
    { … }
  ]
}

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.

Operations

Routing

Use this API operation to look up a payout method.

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

Operations

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.

Balances

Use this API operation to get your account balance information.

Operation	Method	Description
Get spendable balance	GET	Retrieve account balances.

Operations

Payments Direct 1.0 API ( )

API environments

Base URL

URL format

Example base URL

Example fully-qualified URL

API authentication

Generate client ID and client secret

Request an access token

Authentication

Identities

Payments

Get payments

Request

Responses

Was this page helpful?

Get payment by payment ID

Request

Responses

Was this page helpful?

Quotes

Routing

Data requirements

Balances