Payments Direct API (0.0.3)

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

API environments

The Payments Direct API offers the following environments:

Environment	Base URL	Description
UAT	`https://api.test.ripple.com`	UAT environment with simulated currency.
Production	`https://api.ripple.com`	Production environment

API authentication

All {{process.env.VAR_RPD}} 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 UAT 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.

Overview

License

Apache 2.0

Servers

Mock server

https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/

UAT environment with simulated currency

https://api.test.ripple.com/

Production environment

https://api.ripple.com/

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.

Operations

Identities (v3)

Use these API operations to manage your identities with Identity Management v3 (recommended for all new integrations).

Operation	Method	Description
Create an identity (v3)	POST	Create a new identity (INDIVIDUAL/BUSINESS; ORIGINATOR/BENEFICIARY).
Get a list of identies (v3)	GET	Retrieve a list of identities with optional filters (e.g., `paymentRole`, `identityType`).
Get an identity by ID (v3)	GET	Retrieve a specific identity by `identityId` (latest version by default).
Update an identity (v3)	PUT	Update one or more fields; creates a new version.
Deactivate an identity (v3)	DELETE	Set the identity state to `DEACTIVATED` (cannot be used for new payments).
Add a financial instrument (v3)	POST	Add a financial instrument to an identity.
Get a list of financial instruments (v3)	GET	Get a list of financial instruments for an identity.
Get a financial instrument by ID (v3)	GET	Get a specific financial instrument by `financialInstrumentId`.
Update a financial instrument (v3)	PUT	Update a financial instrument by `financialInstrumentId`.
Deactivate a financial instrument (v3)	DELETE	Deactivate a financial instrument by `financialInstrumentId`.

Operations

Identities (v2) — Legacy

Use these API operations to manage your identities for existing integrations built on Identity Management v2.

Versioning notes

v2 identities remain fully supported for ongoing operations.
New integrations should use v3.

Operation	Method	Description
Create a new identity (v2) - Legacy	POST	Create a new v2 legacy identity.
Get a list of identities (v2) - Legacy	GET	Get a list of existing v2 legacy identities.
Get an identity by ID (v2) - Legacy	GET	Get a v2 legacy identity by its unique ID.
Delete an identity (v2) - Legacy	DELETE	Deactivate a v2 legacy identity.

Operations

Quotes

Use these API operations to manage your quotes.

Operation	Method	Description
Create quote collection	POST	Create a collection of quotes.
Get quote collection	GET	Get a quote collection by ID.
Get a quote	GET	Get a specific quote by ID.

Operations

Create quote collection

Request

Creates a collection of quotes for a proposed payment.

Tutorials

Learn how to Create a quote.

Security

Bearer

Bodyapplication/jsonrequired

Create quote collection request

quoteAmountnumber(double)[ 1 .. 100000000 ]required

The amount for which you wish to receive a collection of quotes.

Example: 123.45

quoteAmountTypestringrequired

The type of amount for which you want to get a quote.

Default "SOURCE_AMOUNT"

Enum Value	Description
SOURCE_AMOUNT	Specify this value to get a quote for the amount that you want to send.
DESTINATION_AMOUNT	Specify this value to get a quote for the amount that the beneficiary should receive.

sourceCurrencystring^[a-zA-Z]{3,5}$required

The currency code of the currency that you are sending.

Example: "USD"

destinationCurrencystring^[a-zA-Z]{3,5}$required

The currency code of the currency in which your beneficiary will receive this payment.

Example: "MXN"

sourceCountrystring^[a-zA-Z]{2}$

The country code of the country from where you are sending the funds. This is an ISO 3166-1 alpha-2 code.

Example: "US"

destinationCountrystring^[a-zA-Z]{2}$

The country where the beneficiary is located specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list. If the beneficiary is an individual, then this value is their country of residence. If the beneficiary is an institution, then this value is their the country of incorporation.

Example: "PH"

payoutCategorystring[ 1 .. 128 ] charactersrequired

The name of the payout category.

Enum Value	Description
BANK	Indicates that the payout will be made in fiat currency to a recipient’s bank account through local banking rails.
CRYPTO	Indicates that the payout will be made in stablecoin to a recipient’s crypto wallet address.

Example: "BANK"

payinCategorystring[ 1 .. 128 ] charactersrequired

The name of the pay in category indicating how this payment will be funded.

Enum Value	Description
FUNDED	Indicates that the payment is being made from funds you've deposited with Ripple.
T_PLUS_ONE	Indicates the payment is being made and you will pay the outstanding invoice.

Example: "FUNDED"

destinationBlockchainNetworkstring[ 1 .. 20 ] characters

The name of the blockchain network on which the beneficiary will receive this payment.

Example: "Ethereum"

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/quotes/quote-collection \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteAmount": 123.45,
    "quoteAmountType": "SOURCE_AMOUNT",
    "sourceCurrency": "USD",
    "destinationCurrency": "MXN",
    "sourceCountry": "US",
    "destinationCountry": "PH",
    "payoutCategory": "BANK",
    "payinCategory": "FUNDED",
    "destinationBlockchainNetwork": "Ethereum"
  }'

Responses

Creates a collection of quotes

Bodyapplication/json

quoteCollectionIdstring(uuid)[ 1 .. 36 ] charactersrequired

Unique ID that represents this quote collection.

Example: "11111111-aaaa-2222-bbbb-222222222222"

quotesArray of objects>= 0 itemsrequired

List of quotes

quoteIdstring(uuid)[ 1 .. 36 ] charactersrequired

Unique ID that represents this quote.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

quoteStatusstringrequired

Enum Value	Description
EXPIRED	Expired quote
ACTIVE	Quote that you can accept to create a payment.

Example: "ACTIVE"

quoteAmountTypestring

The type of amount for which you want to get a quote.

Default "SOURCE_AMOUNT"

Enum Value	Description
SOURCE_AMOUNT	Specify this value to get a quote for the amount that you want to send.
DESTINATION_AMOUNT	Specify this value to get a quote for the amount that the beneficiary should receive.

sourceAmountnumber(double)[ 1 .. 100000000 ]

Amount to be sent by the originator.

Example: 123.45

destinationAmountnumber(double)[ 1 .. 100000000 ]

Amount to be received by destination

Example: 2438.19

sourceCurrencystring^[a-zA-Z]{3,5}$required

The currency code of the currency that you are sending.

Example: "USD"

destinationCurrencystring^[a-zA-Z]{3,5}$required

The currency code of the currency in which your beneficiary will receive this payment.

Example: "MXN"

sourceCountrystring^[a-zA-Z]{2}$

The country where the payment originator is located or incorporated, specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list.

Example: "US"

destinationCountrystring^[a-zA-Z]{2}$

The country code to which you wish to send the funds. It follows ISO 3166-1 alpha-2 code

Example: "MX"

payoutCategorystring[ 1 .. 128 ] charactersrequired

Name of the payout category specified in the quote request.

Example: "BANK"

payinCategorystring[ 1 .. 128 ] charactersrequired

The name of payin category specified in the quote request.

Example: "FUNDED"

adjustedExchangeRateobject

Foreign Exchange (FX) rate used to calculate the quote.

adjustedRatenumber(double)

Value of the Foreign Exchange (FX) rate.

Example: 2

feesArray of objects

A summary of fees included in this quote.

totalFeenumber(double)

The value of the total fee included in this quote.

Example: 12.23

feeCurrencystring^[a-zA-Z]{3,5}$

The currency in which fees are charged.

Example: "USD"

feeBreakdownArray of objects

An array of fees that provides a breakdown of how the total fees is calculated for this quote.

calculatedFeenumber(double)

Value of the fee when the configured fee unit is applied against the value.

Example: 2.43

feeNamestring[ 1 .. 128 ] characters

The name of the fee.

Example: "Service fee"

feeDescriptionstring[ 1 .. 256 ] characters

Description of the fee.

Example: "The service fee charged for this transaction."

taxesArray of objects

A summary of taxes included in this quote.

totalTaxesnumber(double)

The value of the total taxes included in this quote.

Example: 5.12

taxCurrencystring^[a-zA-Z]{3,5}$

The currency in which taxes are charged.

Example: "USD"

taxBreakdownArray of objects

An array of taxes with details such as tax description, rate, name and tax amount.

taxAmountnumber(double)

tax amount for this tax line item.

Example: 2.43

taxNamestring[ 1 .. 128 ] characters

The name of the tax.

Example: "ISS/ VAT/ GST etc"

taxDescriptionstring[ 1 .. 256 ] characters

GST service fee tax .

Example: "The service fee tax charged for this transaction."

taxRatenumber(double)

The tax rate applied to calculate the tax amount.

Example: 5

createdAtstring(date-time)[ 1 .. 128 ] characters

The time when this quote was created, specified in UTC.

Example: "2023-11-02T18:26:00.000123Z"

expiresAtstring(date-time)[ 1 .. 128 ] characters

The time when this quote expires, specified in UTC.

Example: "2023-11-02T18:26:00.000123Z"

destinationBlockchainNetworkstring[ 1 .. 20 ] characters

The name of the blockchain network on which the beneficiary will receive this payment.

Example: "Ethereum"

Response

application/json

{
  "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  "quotes": [
    { … }
  ]
}

Get quote collection

Request

Security

Bearer

Path

quote-collection-idstring(uuid)required

The unique identifier of the quote collection you want to retrieve

Example: 11111111-aaaa-2222-bbbb-222222222222

curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/quotes/quote-collection/11111111-aaaa-2222-bbbb-222222222222 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Valid quote collection found

Bodyapplication/json

quoteCollectionIdstring(uuid)[ 1 .. 36 ] charactersrequired

Unique ID that represents this quote collection.

Example: "11111111-aaaa-2222-bbbb-222222222222"

quotesArray of objects>= 0 itemsrequired

List of quotes

quoteIdstring(uuid)[ 1 .. 36 ] charactersrequired

Unique ID that represents this quote.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

quoteStatusstringrequired

Enum Value	Description
EXPIRED	Expired quote
ACTIVE	Quote that you can accept to create a payment.

Example: "ACTIVE"

quoteAmountTypestring

The type of amount for which you want to get a quote.

Default "SOURCE_AMOUNT"

Enum Value	Description
SOURCE_AMOUNT	Specify this value to get a quote for the amount that you want to send.
DESTINATION_AMOUNT	Specify this value to get a quote for the amount that the beneficiary should receive.

sourceAmountnumber(double)[ 1 .. 100000000 ]

Amount to be sent by the originator.

Example: 123.45

destinationAmountnumber(double)[ 1 .. 100000000 ]

Amount to be received by destination

Example: 2438.19

sourceCurrencystring^[a-zA-Z]{3,5}$required

The currency code of the currency that you are sending.

Example: "USD"

destinationCurrencystring^[a-zA-Z]{3,5}$required

The currency code of the currency in which your beneficiary will receive this payment.

Example: "MXN"

sourceCountrystring^[a-zA-Z]{2}$

The country where the payment originator is located or incorporated, specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list.

Example: "US"

destinationCountrystring^[a-zA-Z]{2}$

The country code to which you wish to send the funds. It follows ISO 3166-1 alpha-2 code

Example: "MX"

payoutCategorystring[ 1 .. 128 ] charactersrequired

Name of the payout category specified in the quote request.

Example: "BANK"

payinCategorystring[ 1 .. 128 ] charactersrequired

The name of payin category specified in the quote request.

Example: "FUNDED"

adjustedExchangeRateobject

Foreign Exchange (FX) rate used to calculate the quote.

adjustedRatenumber(double)

Value of the Foreign Exchange (FX) rate.

Example: 2

feesArray of objects

A summary of fees included in this quote.

totalFeenumber(double)

The value of the total fee included in this quote.

Example: 12.23

feeCurrencystring^[a-zA-Z]{3,5}$

The currency in which fees are charged.

Example: "USD"

feeBreakdownArray of objects

An array of fees that provides a breakdown of how the total fees is calculated for this quote.

calculatedFeenumber(double)

Value of the fee when the configured fee unit is applied against the value.

Example: 2.43

feeNamestring[ 1 .. 128 ] characters

The name of the fee.

Example: "Service fee"

feeDescriptionstring[ 1 .. 256 ] characters

Description of the fee.

Example: "The service fee charged for this transaction."

taxesArray of objects

A summary of taxes included in this quote.

totalTaxesnumber(double)

The value of the total taxes included in this quote.

Example: 5.12

taxCurrencystring^[a-zA-Z]{3,5}$

The currency in which taxes are charged.

Example: "USD"

taxBreakdownArray of objects

An array of taxes with details such as tax description, rate, name and tax amount.

taxAmountnumber(double)

tax amount for this tax line item.

Example: 2.43

taxNamestring[ 1 .. 128 ] characters

The name of the tax.

Example: "ISS/ VAT/ GST etc"

taxDescriptionstring[ 1 .. 256 ] characters

GST service fee tax .

Example: "The service fee tax charged for this transaction."

taxRatenumber(double)

The tax rate applied to calculate the tax amount.

Example: 5

createdAtstring(date-time)[ 1 .. 128 ] characters

The time when this quote was created, specified in UTC.

Example: "2023-11-02T18:26:00.000123Z"

expiresAtstring(date-time)[ 1 .. 128 ] characters

The time when this quote expires, specified in UTC.

Example: "2023-11-02T18:26:00.000123Z"

destinationBlockchainNetworkstring[ 1 .. 20 ] characters

The name of the blockchain network on which the beneficiary will receive this payment.

Example: "Ethereum"

Response

application/json

{
  "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  "quotes": [
    { … }
  ]
}

Get quote

Request

Security

Bearer

Path

quote-idstring(uuid)required

The unique identifier of the quote to retrieve

Example: 22222222-aaaa-2222-bbbb-222222222222

curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/quotes/22222222-aaaa-2222-bbbb-222222222222 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Valid quote found

Bodyapplication/json

quoteIdstring(uuid)[ 1 .. 36 ] charactersrequired

Unique ID that represents this quote.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

quoteStatusstringrequired

Enum Value	Description
EXPIRED	Expired quote
ACTIVE	Quote that you can accept to create a payment.

Example: "ACTIVE"

quoteAmountTypestring

The type of amount for which you want to get a quote.

Default "SOURCE_AMOUNT"

Enum Value	Description
SOURCE_AMOUNT	Specify this value to get a quote for the amount that you want to send.
DESTINATION_AMOUNT	Specify this value to get a quote for the amount that the beneficiary should receive.

sourceAmountnumber(double)[ 1 .. 100000000 ]

Amount to be sent by the originator.

Example: 123.45

destinationAmountnumber(double)[ 1 .. 100000000 ]

Amount to be received by destination

Example: 2438.19

sourceCurrencystring^[a-zA-Z]{3,5}$required

The currency code of the currency that you are sending.

Example: "USD"

destinationCurrencystring^[a-zA-Z]{3,5}$required

The currency code of the currency in which your beneficiary will receive this payment.

Example: "MXN"

sourceCountrystring^[a-zA-Z]{2}$

The country where the payment originator is located or incorporated, specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list.

Example: "US"

destinationCountrystring^[a-zA-Z]{2}$

The country code to which you wish to send the funds. It follows ISO 3166-1 alpha-2 code

Example: "MX"

payoutCategorystring[ 1 .. 128 ] charactersrequired

Name of the payout category specified in the quote request.

Example: "BANK"

payinCategorystring[ 1 .. 128 ] charactersrequired

The name of payin category specified in the quote request.

Example: "FUNDED"

adjustedExchangeRateobject

Foreign Exchange (FX) rate used to calculate the quote.

adjustedRatenumber(double)

Value of the Foreign Exchange (FX) rate.

Example: 2

feesArray of objects

A summary of fees included in this quote.

totalFeenumber(double)

The value of the total fee included in this quote.

Example: 12.23

feeCurrencystring^[a-zA-Z]{3,5}$

The currency in which fees are charged.

Example: "USD"

feeBreakdownArray of objects

An array of fees that provides a breakdown of how the total fees is calculated for this quote.

calculatedFeenumber(double)

Value of the fee when the configured fee unit is applied against the value.

Example: 2.43

feeNamestring[ 1 .. 128 ] characters

The name of the fee.

Example: "Service fee"

feeDescriptionstring[ 1 .. 256 ] characters

Description of the fee.

Example: "The service fee charged for this transaction."

taxesArray of objects

A summary of taxes included in this quote.

totalTaxesnumber(double)

The value of the total taxes included in this quote.

Example: 5.12

taxCurrencystring^[a-zA-Z]{3,5}$

The currency in which taxes are charged.

Example: "USD"

taxBreakdownArray of objects

An array of taxes with details such as tax description, rate, name and tax amount.

taxAmountnumber(double)

tax amount for this tax line item.

Example: 2.43

taxNamestring[ 1 .. 128 ] characters

The name of the tax.

Example: "ISS/ VAT/ GST etc"

taxDescriptionstring[ 1 .. 256 ] characters

GST service fee tax .

Example: "The service fee tax charged for this transaction."

taxRatenumber(double)

The tax rate applied to calculate the tax amount.

Example: 5

createdAtstring(date-time)[ 1 .. 128 ] characters

The time when this quote was created, specified in UTC.

Example: "2023-11-02T18:26:00.000123Z"

expiresAtstring(date-time)[ 1 .. 128 ] characters

The time when this quote expires, specified in UTC.

Example: "2023-11-02T18:26:00.000123Z"

destinationBlockchainNetworkstring[ 1 .. 20 ] characters

The name of the blockchain network on which the beneficiary will receive this payment.

Example: "Ethereum"

Response

application/json

{
  "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  "quoteStatus": "ACTIVE",
  "quoteAmountType": "SOURCE_AMOUNT",
  "sourceAmount": 123.45,
  "destinationAmount": 2438.19,
  "sourceCurrency": "USD",
  "destinationCurrency": "MXN",
  "sourceCountry": "US",
  "destinationCountry": "MX",
  "payoutCategory": "BANK",
  "payinCategory": "FUNDED",
  "adjustedExchangeRate": {
    "adjustedRate": 2
  },
  "fees": [
    { … }
  ],
  "taxes": [
    { … }
  ],
  "createdAt": "2023-11-02T18:26:00.000123Z",
  "expiresAt": "2023-11-02T18:26:00.000123Z",
  "destinationBlockchainNetwork": "Ethereum"
}

Payments (v3)

Use these API operations to manage your payments with Payment Management v3 (recommended for all new integrations).

Operation	Method	Description
Search payments (v3)	POST	Search for v3 payments based on filtering criteria.
Create a payment (v3)	POST	Create a v3payment by accepting a quote.
Get payment by payment ID (v3)	GET	Get a specific v3 payment by payment ID.
Get state transitions by payment ID (v3)	GET	Get the state transitions for a specific v3 payment by payment ID.
Update payment labels (v3)	PATCH	Update the labels for a specific v3 payment by payment ID.

Operations

Payments (v2) - Legacy

Use these API operations to manage your v2 legacy payments.

Operation	Method	Description
Search payments (v2) - Legacy)	POST	Search for legacy v2 payments based on filtering criteria.
Create a payment (v2) - Legacy)	POST	Create a legacy v2 payment by accepting a quote.
Get a payment by payment ID (v2) - Legacy	GET	Get a specific legacy v2 payment by payment ID.
Get state transitions by payment ID (v2) - Legacy	GET	Get the state transitions for a specific legacy v2 payment by payment ID.
Update payment labels (v2) - Legacy	PATCH	Update the labels for a specific legacy v2 payment by payment ID.

Operations

Ledger

Use these API operation to fetch ledger transactions and check balances.

Operation	Method	Description
Get balances	GET	View your existing balances
Get ledger transactions	GET	View your ledger transactions.

Operations

Payments Direct API (0.0.3)

API environments

API authentication

Generate client ID and client secret

Request an access token

Authentication

Identities (v3)

Identities (v2) — Legacy

Quotes

Create quote collection

Request

Responses

Was this page helpful?

Get quote collection

Request

Responses

Was this page helpful?

Get quote

Request

Responses

Was this page helpful?

Payments (v3)

Payments (v2) - Legacy

Ledger