Skip to content

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 URLDescription
UAThttps://api.test.ripple.comUAT environment with simulated currency.
Productionhttps://api.ripple.comProduction 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:

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

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

OperationMethodDescription
Request an access tokenPOSTRequest an access token for authentication with Ripple APIs.
Test access tokenGETTest 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).

OperationMethodDescription
Create an identity (v3)POSTCreate a new identity (INDIVIDUAL/BUSINESS; ORIGINATOR/BENEFICIARY).
Get a list of identies (v3)GETRetrieve a list of identities with optional filters (e.g., paymentRole, identityType).
Get an identity by ID (v3)GETRetrieve a specific identity by identityId (latest version by default).
Update an identity (v3)PUTUpdate one or more fields; creates a new version.
Deactivate an identity (v3)DELETESet the identity state to DEACTIVATED (cannot be used for new payments).
Add a financial instrument (v3)POSTAdd a financial instrument to an identity.
Get a list of financial instruments (v3)GETGet a list of financial instruments for an identity.
Get a financial instrument by ID (v3)GETGet a specific financial instrument by financialInstrumentId.
Update a financial instrument (v3)PUTUpdate a financial instrument by financialInstrumentId.
Deactivate a financial instrument (v3)DELETEDeactivate 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.
OperationMethodDescription
Create a new identity (v2) - LegacyPOSTCreate a new v2 legacy identity.
Get a list of identities (v2) - LegacyGETGet a list of existing v2 legacy identities.
Get an identity by ID (v2) - LegacyGETGet a v2 legacy identity by its unique ID.
Delete an identity (v2) - LegacyDELETEDeactivate a v2 legacy identity.
Operations

Create a new identity (v2) - Legacy

Request

Create a new identity.

Security
Bearer
Bodyapplication/jsonrequired
piiDataobjectrequired

PII data in JSON format.

You must use the correct piiData schema for the type of identity you want to create.

Note: Reach out to your Ripple liaison to get this schema.

property name*anyadditional property
identityTypestringrequired

The type of the identity

Enum ValueDescription
BENEFICIARY

Identity associated with the beneficiary.

ORIGINATOR

Identity associated with the party originating the payment.

Example: "BENEFICIARY"
nickNamestring

The nickname for the identity provided at the time of identity creation

Example: "MyCompany"
useCaseTypestringrequired

Classification of the identity: • INDIVIDUAL - A natural person. • BUSINESS - A legal entity such as a company or institution.

Enum"INDIVIDUAL""BUSINESS"
Example: "BUSINESS"
curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/identities \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "piiData": {},
    "identityType": "BENEFICIARY",
    "nickName": "MyCompany",
    "useCaseType": "BUSINESS"
  }'

Responses

successful operation

Bodyapplication/json
identityIdstringrequired

The unique ID of the identity

Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"
versionintegerrequired

The version number of the identity

Example: 2
Response
application/json
{
  "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  "version": 2
}

Get a list of identities (v2) - Legacy

Request

Get a list of identities that match the query parameters.

Note: Depending on the number of identities in your account, not all of them may be returned even if they match your query parameters.

Security
Bearer
Query
identityTypestring

The type of identities you want to retrieve

Enum ValueDescription
BENEFICIARY

Identity associated with the beneficiary.

ORIGINATOR

Identity associated with the party originating the payment.

Example: identityType=BENEFICIARY
nickNamestring

The nickname for the identity provided at the time of identity creation

Example: nickName=Successful Beneficiary
curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/identities?identityType=BENEFICIARY&nickName=Successful+Beneficiary' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Requested identity info in JSON format

Bodyapplication/json
dataArray of objects

The list of the identities that match the query parameters

identityIdstringrequired

The unique ID of the identity

Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"
nickNamestringrequired

The nickname of the identity provided at the time of identity creation.

Example: "MyCompany"
createdAtstring(date-time)required

The time at which the identity was created

Example: "2023-11-02T18:26:00.000Z"
identityTypestringrequired

The type of the identity

Enum ValueDescription
BENEFICIARY

Identity associated with the beneficiary.

ORIGINATOR

Identity associated with the party originating the payment.

Example: "BENEFICIARY"
useCaseTypestringrequired

Classification of the identity: • INDIVIDUAL - A natural person. • BUSINESS - A legal entity such as a company or institution.

Enum"INDIVIDUAL""BUSINESS"
Example: "BUSINESS"
Response
application/json
{
  "data": [
    { … }
  ]
}

Get an identity by ID (v2) - Legacy

Request

Retrieve a specific identity by ID. If version is not provided, the latest version is returned.

Security
Bearer
Path
identity-idstringrequired

The ID of the identity to retrieve.

Example: 146f3c51-c313-47ce-b6f2-691c5a238b3e
Query
versioninteger>= 1

Specific version to retrieve. If omitted, returns the latest version.

Example: version=2
curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/identities/146f3c51-c313-47ce-b6f2-691c5a238b3e?version=2' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Identity details.

Bodyapplication/json
identityIdstringrequired

The unique ID of the identity

Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"
identityTypestringrequired

The type of the identity

Enum ValueDescription
BENEFICIARY

Identity associated with the beneficiary.

ORIGINATOR

Identity associated with the party originating the payment.

Example: "BENEFICIARY"
createdAtstring(date-time)required

The time at which the identity was created

Example: "2023-11-02T18:26:00.000Z"
identityStatestringrequired

Lifecycle state of the identity: • ACTIVE - The identity exists and can be used. • BLOCKED - The identity exists but is restricted from use. • DEACTIVATED - The identity is inactive and cannot be used for new payments.

Enum"ACTIVE""BLOCKED""DEACTIVATED"
Example: "ACTIVE"
nickNamestring

The nickname for the identity provided at the time of identity creation

Example: "MyCompany"
piiDataobjectrequired

PII data in JSON format

property name*anyadditional property
versionintegerrequired

The version number of the identity

Example: 2
useCaseTypestringrequired

Classification of the identity: • INDIVIDUAL - A natural person. • BUSINESS - A legal entity such as a company or institution.

Enum"INDIVIDUAL""BUSINESS"
Example: "BUSINESS"
Response
application/json
{
  "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  "identityType": "BENEFICIARY",
  "createdAt": "2023-11-02T18:26:00.000Z",
  "identityState": "ACTIVE",
  "nickName": "MyCompany",
  "piiData": {},
  "version": 2,
  "useCaseType": "BUSINESS"
}

Delete an identity (v2) - Legacy

Request

Deactivate an identity and its financial instruments. Deactivation is permanent and prevents further use in payments. Historical versions remain available for audit.

Security
Bearer
Path
identity-idstringrequired

ID of the identity to deactivate.

Example: 146f3c51-c313-47ce-b6f2-691c5a238b3e
curl -i -X DELETE \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/identities/146f3c51-c313-47ce-b6f2-691c5a238b3e \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Identity deactivated.

Response
No content

Quotes

Use these API operations to manage your quotes.

OperationMethodDescription
Create quote collectionPOSTCreate a collection of quotes.
Get quote collectionGETGet a quote collection by ID.
Get a quoteGETGet 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).

OperationMethodDescription
Search payments (v3)POSTSearch for v3 payments based on filtering criteria.
Create a payment (v3)POSTCreate a v3payment by accepting a quote.
Get payment by payment ID (v3)GETGet a specific v3 payment by payment ID.
Get state transitions by payment ID (v3)GETGet the state transitions for a specific v3 payment by payment ID.
Update payment labels (v3)PATCHUpdate the labels for a specific v3 payment by payment ID.
Operations

Payments (v2) - Legacy

Use these API operations to manage your v2 legacy payments.

OperationMethodDescription
Search payments (v2) - Legacy)POSTSearch for legacy v2 payments based on filtering criteria.
Create a payment (v2) - Legacy)POSTCreate a legacy v2 payment by accepting a quote.
Get a payment by payment ID (v2) - LegacyGETGet a specific legacy v2 payment by payment ID.
Get state transitions by payment ID (v2) - LegacyGETGet the state transitions for a specific legacy v2 payment by payment ID.
Update payment labels (v2) - LegacyPATCHUpdate the labels for a specific legacy v2 payment by payment ID.
Operations

Ledger

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

OperationMethodDescription
Get balancesGETView your existing balances
Get ledger transactionsGETView your ledger transactions.
Operations