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

Request an access token

Request

Request an access token for authentication with Ripple APIs.

You need to request a token for the environment you want to authenticate with.

Note: The length of the access token isn't fixed, hence it can vary. Avoid validating tokens based on character length.

Tutorials

Learn how to Request an access token.

Environments

Environment	Domain	Description
Test	`api.test.ripple.com`	Test environment with simulated currency.
Production	`api.ripple.com`	Production environment for Ripple Payments Direct

Security

BasicAuth

Headers

Authorizationstring

Optional base64-encoded client_id:client_secret. If provided here they aren't required in the request body.

Example: Basic ZGVtbzpwQDU1dzByZA==

Body

required

client_idstringrequired

The client ID associated with a specific set of API credentials.

Example: "{YOUR_CLIENT_ID}"

client_secretstringrequired

The client secret associated with a specific set of API credentials.

Example: "{YOUR_CLIENT_SECRET}"

audiencestringrequired

The value of the audience field is based on URN syntax.

Format: urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}

The first component is urn:ripplenetxcurrent-.
The second component refers to the environment you want to access.
The third component is your tenant ID. Ripple integration engineers provide this component during training.

Environment	Environment string	Description
Test	`test`	Test environment with simulated partners and simulated currency.
Production	`prod`	Production environment for Ripple's internal services.

Example: urn:ripplexcurrent-test:{YOUR_TENANT_ID}

Example: "urn:ripplexcurrent-test:{YOUR_TENANT_ID}"

grant_typestringrequired

Set the grant-type for this client credentials request. This must be set to client_credentials.

Value"client_credentials"

Example: "client_credentials"

curl -i -X POST \
  -u <username>:<password> \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/oauth/token \
  -H 'Authorization: Basic ZGVtbzpwQDU1dzByZA==' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "{YOUR_CLIENT_ID}",
    "client_secret": "{YOUR_CLIENT_SECRET}",
    "audience": "urn:ripplexcurrent-test:{YOUR_TENANT_ID}",
    "grant_type": "client_credentials"
  }'

Responses

Returns the authentication response object that includes the token, type, scopes, and expiry.

Bodyapplication/json

access_tokenstring

The bearer token you use when authenticating with a Ripple API.

Example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ"

scopestring

List of scopes applied to your access_token.

Example: "pos:payments:create quote_collection:quote:create quote:quote:read pos:payments:read pcs_config:external_read data_requirements:read identities:create identities:read identities:write ledger:balance:read ledger:read"

expires_ininteger(int64)

How long your access_token is valid. You need to request a new token when it expires.

Example: 3600

token_typestring

The type of token. Ripple APIs use Bearer auth tokens.

Example: "Bearer"

Response

application/json

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
  "scope": "pos:payments:create quote_collection:quote:create quote:quote:read pos:payments:read pcs_config:external_read data_requirements:read identities:create identities:read identities:write ledger:balance:read ledger:read",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Test access token

Request

Test if an access token can be used for authentication with Ripple APIs and how much time remains on it.

Security

Bearer

curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/oauth/token/test \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

If a valid bearer token is supplied, the time remaining before the token expires is returned.

Bodyapplication/jsonArray [

messagestring

Example: "token_ok"

seconds_to_expiryinteger(int64)

Remaining time in seconds before the tested token expires.

Example: 3600

]

Response

application/json

[
  {
    "message": "token_ok",
    "seconds_to_expiry": 3600
  }
]

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

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

Request an access token

Request

Environments

Responses

Was this page helpful?

Test access token

Request

Responses

Was this page helpful?

Identities (v3)

Identities (v2) — Legacy

Quotes

Payments (v3)

Payments (v2) - Legacy

Ledger