Payments Direct API (2026.04)
View as Markdown
Open this page as Markdown
Copy for LLM
Copy page as Markdown for LLMs
Open in Claude
Get insights from Claude
Open in ChatGPT
Get insights from ChatGPT

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 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:

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.

Download OpenAPI description

payments-direct-2-api.json

payments-direct-2-api.yaml

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). Note: Identity Management v3 is scheduled for release in April 2026. For early access or specific migration details, please contact your Ripple representative. For more information about identity management, see Payment identities and Financial instruments.

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).
Get an identity by internal ID (v3)	GET	Retrieve an active identity by client-provided `internalId`.
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

Quotes (v3)

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

Create a quote collection to preview the cost and terms of a proposed payment before initiating it.

What's new in v3:

payoutCategory and destinationBlockchainNetwork are no longer accepted in requests.
paymentRail is added as an optional field in the request to allow filtering quotes by a specific payment rail. When paymentRail is not passed, quotes will be returned for all supported payment rails.

Tutorials

paymentRail is added as an optional field in the request to allow filtering quotes by a specific payment rail. When paymentRail is not passed, quotes will be returned for all supported payment rails. For a list of supported values, see Payment rail reference.

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: "MX"

payinCategorystring[ 1 .. 128 ] charactersrequired

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

Enum Value	Description
PRE_FUNDING	Indicates that the payment is being made from funds you've deposited with Ripple.
CREDIT_FUNDING	Indicates the payment is being made and you will pay the outstanding invoice.
JIT_FUNDING	Indicates that the payment is being made and you will pay the outstanding amount before the payment expires.

Example: "PRE_FUNDING"

paymentRailstring[ 1 .. 50 ] characters

The payment rail on which the beneficiary will receive this payment. This value may be used to filter quotes to a specific subset of supported payout rails. If not provided, quotes will be returned for all supported payout rails. For a list of supported values, see Payment rail reference.

Enum Value	Description
RTP	Indicates that the payout will be made in fiat currency to a recipient’s bank account through the RTP network.
ACH	Indicates that the payout will be made in fiat currency to a recipient’s bank account through the ACH network.
WIRE	Indicates that the payout will be made in fiat currency to a recipient’s bank account through the wire transfer network.
ETHEREUM	Indicates that the payout will be made in stablecoin to a recipient's Ethereum wallet address.

Example: "SPEI"

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/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": "MX",
    "payinCategory": "PRE_FUNDING",
    "paymentRail": "SPEI"
  }'

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"

payinCategorystring[ 1 .. 128 ] charactersrequired

The name of payin category specified in the quote request.

Example: "PRE_FUNDING"

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

paymentRailstring[ 1 .. 30 ] characters

The payment rail associated with this fee line item.

Example: "SPEI"

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"

paymentRailstring[ 1 .. 50 ] characters

The payment rail used for this quote.

Example: "SPEI"

Response

application/json

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

Get quote collection

Request

Retrieve a previously created quote collection by its unique identifier.

Use this endpoint to check the status of quotes (ACTIVE or EXPIRED) and retrieve quote details needed for payment creation.

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/v3/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"

payinCategorystring[ 1 .. 128 ] charactersrequired

The name of payin category specified in the quote request.

Example: "PRE_FUNDING"

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

paymentRailstring[ 1 .. 30 ] characters

The payment rail associated with this fee line item.

Example: "SPEI"

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"

paymentRailstring[ 1 .. 50 ] characters

The payment rail used for this quote.

Example: "SPEI"

Response

application/json

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

Get a quote

Request

Retrieve a specific quote by its unique identifier.

Use this endpoint to:

Verify quote details before creating a payment
Check if a quote is still active (not expired)
Retrieve the quoteId needed for payment creation

Note: Quotes expire after a defined period. Check the quoteStatus field to confirm the quote is ACTIVE before using it to create a payment.

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/v3/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"

payinCategorystring[ 1 .. 128 ] charactersrequired

The name of payin category specified in the quote request.

Example: "PRE_FUNDING"

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

paymentRailstring[ 1 .. 30 ] characters

The payment rail associated with this fee line item.

Example: "SPEI"

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"

paymentRailstring[ 1 .. 50 ] characters

The payment rail used for this quote.

Example: "SPEI"

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",
  "payinCategory": "PRE_FUNDING",
  "adjustedExchangeRate": {
    "adjustedRate": 2
  },
  "fees": [
    { … }
  ],
  "taxes": [
    { … }
  ],
  "createdAt": "2023-11-02T18:26:00.000123Z",
  "expiresAt": "2023-11-02T18:26:00.000123Z",
  "paymentRail": "SPEI"
}

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

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 (2026.04)
View as Markdown
Open this page as Markdown
Copy for LLM
Copy page as Markdown for LLMs
Open in Claude
Get insights from Claude
Open in ChatGPT
Get insights from ChatGPT

API environments

API authentication

Generate client ID and client secret

Request an access token

Authentication

Identities (v3)

Quotes (v3)

Create quote collection

Request

Responses

Was this page helpful?

Get quote collection

Request

Responses

Was this page helpful?

Get a quote

Request

Responses

Was this page helpful?

Payments (v3)

Ledger

Payments Direct API (2026.04)View as MarkdownView as MarkdownOpen this page as MarkdownCopy for LLMCopy page as Markdown for LLMsOpen in ClaudeGet insights from ClaudeOpen in ChatGPTGet insights from ChatGPT

API environments

API authentication

Generate client ID and client secret

Request an access token

Authentication

Identities (v3)

Quotes (v3)

Create quote collection

Request

Responses

Was this page helpful?

Get quote collection

Request

Responses

Was this page helpful?

Get a quote

Request

Responses

Was this page helpful?

Payments (v3)

Ledger

Payments Direct API (2026.04)
View as Markdown
Open this page as Markdown
Copy for LLM
Copy page as Markdown for LLMs
Open in Claude
Get insights from Claude
Open in ChatGPT
Get insights from ChatGPT