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
Test	`https://api.test.ripple.com`	Test 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 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.

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/

Test 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

Use these API operations to manage your identities.

Operation	Method	Description
Create an identity	POST	Create a new identity.
List identities	GET	Get a list of existing identities.
Get an identity by ID	GET	Get an identity by its unique ID.
Deactivate an identity	DELETE	Deactivate an identity.

Operations

Payments

Use these API operations to manage your payments.

Operation	Method	Description
Search payments	POST	Search for payments based on filtering criteria.
Create a payment	POST	Create a payment by accepting a quote.
Get payment by payment ID	GET	Get a specific payment by payment ID.

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

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

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

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": [
    { … }
  ],
  "createdAt": "2023-11-02T18:26:00.000123Z",
  "expiresAt": "2023-11-02T18:26:00.000123Z",
  "destinationBlockchainNetwork": "Ethereum"
}

Balances

Use this API operation to view your balances.

Operation	Method	Description
Get balances	GET	View your existing balances

Operations

Payments Direct API (0.0.3)

API environments

API authentication

Generate client ID and client secret

Request an access token

Authentication

Identities

Payments

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?

Balances