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

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

Get available balances

Request

Security
Bearer
Query
currencystring

The currency for which you want to get the balance.

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/balances?currency=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response containing balance details.

Bodyapplication/json
timestampstring(date-time)required

Timestamp of the balance response.

Example: "2025-01-10T00:00:00.000000Z"
balancesArray of objectsrequired

List of available prefund balances.

fundingTypeanyrequired

The funding method associated with your account.

ValueDescription
FUNDED

Indicates that you initiate payments using the funds you added to your account.

currencystringrequired

Currency code.

Example: "USD"
availableBalancenumberrequired

Available funded balance that you can use to initiate payments.

Example: 1000
reservedBalancenumberrequired

Amount reserved to complete in-progress transactions. You can't use this amount to initiate new payments.

Example: 100
Response
application/json
{
  "timestamp": "2025-01-10T00:00:00.000000Z",
  "balances": [
    { … }
  ]
}

Get ledger transactions

Request

Retrieve a paginated list of ledger transactions for your tenant within a specified date and time range. This endpoint returns detailed transaction data, including amounts, references, operations, and running balances, so you can reconcile balance changes over time for a given currency.

Security
Bearer
Query
currencystringrequired

Three-letter ISO 4217 currency code for the transactions to return (for example, USD).

Example: currency=USD
start-dttmstring(date-time)required

Start of the date and time range (inclusive), in UTC, for which you want to retrieve ledger transactions.

Example: start-dttm=2022-02-27T08:30:00Z
end-dttmstring(date-time)required

End of the date and time range (exclusive), in UTC, for which you want to retrieve ledger transactions.

Example: end-dttm=2022-02-27T08:30:00Z
statusstring

Filter results by transaction status. Allowed values: - SUCCESS: the ledger transaction completed successfully. - PENDING: reserved for future use to represent an in-flight ledger transaction.

txnReferencestring

Filter results by an exact transaction reference. Use this to locate all ledger transactions associated with a specific external reference.

page-sizeinteger[ 1 .. 50 ]required

Number of records to return in the response page. Use page-size together with offset for offset-based pagination

Default 25
offsetinteger

Number of records to skip before starting to return results. Use this with page-size to implement offset-based pagination. For example, offset=25&page-size=25 returns the second page of results.

sort-keystring

Field to use for sorting the results. Allowed values include:

  • CREATED_AT: sort by transaction creation timestamp.
  • STATEMENT_OPERATION: sort by the operation type (for example, CREDIT, DEBIT).
  • STATEMENT_SOURCE: sort by the transaction source (for example, PAYMENTS, BANK).
  • STATEMENT_STATUS: sort by the ledger transaction status.
  • STATEMENT_TXN_REFERENCE: sort by the transaction reference.
  • STATEMENT_UPDATED_AT: sort by the last update timestamp.
sort-directionstring

Sort direction. Allowed values:

  • ASC: ascending order.
  • DESC: descending order.
curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/ledger-transactions?currency=USD&start-dttm=2022-02-27T08%3A30%3A00Z&end-dttm=2022-02-27T08%3A30%3A00Z&status=string&txnReference=string&page-size=25&offset=0&sort-key=string&sort-direction=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

A page of ledger statement transactions for the tenant that match the specified query parameters.

Bodyapplication/jsonArray [
offsetinteger

Offset used in the request to skip a specific number of records.

Example: 0
pageSizeinteger

Number of records requested per page

Example: 25
pageElementsinteger

Number of records returned in requested page

Example: 25
totalinteger(int64)

Total number of records available for the given filters.

Example: 1000
statementTransactionsArray of objects

Statement transaction details for the tenant.

tenantstring

Identifier of the tenant that owns this ledger transaction.

Example: "rocketfuel"
amountnumber

Amount of the transaction applied to the tenant’s ledger account.

Example: 100
currencystring

Three-letter ISO 4217 currency code of the transaction.

Example: "USD"
operationstring

Operation performed on the tenant’s prefunded ledger account.

Enum ValueDescription
CREDIT

Credit to the ledger account.

RESERVE

Funds reserved in an intermediate state.

DEBIT

Funds debited from the reserved state.

RELEASE

Reserved funds released back to the account.

VOID_PREFUND_BALANCE

Prefund balance has been voided. [Deprecated]

OVERRIDE_PREFUND_BALANCE

Prefund balance has been overridden. [Deprecated]

VOID_BALANCE

Balance has been voided.

OVERRIDE_BALANCE

Balance has been overridden.

txnSourcestring

Source of the ledger transaction (for example, which system or flow created it).

Enum ValueDescription
PAYMENTS

Created by a payments flow.

BANK

Created by a bank transaction.

POSTED_PAYMENT

Created by a posted payment operation.

CREDIT_MEMO

Created by a credit memo.

MANUAL

Created manually via API.

statusstring

State of the ledger transaction.

Enum ValueDescription
SUCCESS

Ledger transaction completed successfully.

PENDING

Reserved for future use to represent an in-flight ledger transaction.

createdDttmstring(date-time)

Timestamp (UTC) when the ledger transaction was created.

Example: "2024-06-01T00:00:00.000000Z"
updatedDttmstring(date-time)

Timestamp (UTC) when the ledger transaction was last updated.

Example: "2024-06-01T00:00:00.000000Z"
availableBalanceBeforenumber

Available ledger account balance (in the transaction currency) immediately before this transaction was applied.

Example: 100
availableBalanceAfternumber

Available ledger account balance (in the transaction currency) immediately after this transaction was applied.

Example: 90
]
Response
application/json
[
  {
    "offset": 0,
    "pageSize": 25,
    "pageElements": 25,
    "total": 1000,
    "statementTransactions": [ … ]
  }
]