# Payments Direct API 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 {% $env.PUBLIC_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](/products/payments-direct-2/@v2026.03/api-docs/payments-direct-api/payments-direct-2-api/authentication/authenticate) operation. ### Request an access token To get an access token, use the [Request an access token](/products/payments-direct-2/@v2026.03/api-docs/payments-direct-api/payments-direct-2-api/authentication/authenticate) 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. Version: 2026.03 License: Apache 2.0 ## Servers UAT environment with simulated currency ``` https://api.test.ripple.com ``` Production environment ``` https://api.ripple.com ``` ## Security ### Bearer Type: http Scheme: bearer Bearer Format: JWT ### BasicAuth Type: http Scheme: basic ## Download OpenAPI description [Payments Direct API](https://docs.ripple.com/_bundle/products/payments-direct-2/@v2026.03/api-docs/payments-direct-api/payments-direct-2-api.yaml) ## Authentication Use these API operations to manage your authentication tokens. | Operation | Method | Description | | --- | --- | --- | | [Request an access token](#operation/authenticate) | POST | Request an access token for authentication with Ripple APIs. | | [Test access token](#operation/testAuthToken) | GET | Test if an access token can be used for authentication. | ### Request an access token - [POST /v2/oauth/token](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/authentication/authenticate.md): 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. #### Environments | Environment | Domain | Description | | --- | --- | --- | | Test | api.test.ripple.com | Test environment with simulated currency. | | Production | api.ripple.com | Production environment for Ripple Payments Direct | ### Test access token - [GET /v2/oauth/token/test](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/authentication/testauthtoken.md): Test if an access token can be used for authentication with Ripple APIs and how much time remains on it. ## Identities (v3) **Note:** **Identity Management v3** is scheduled for release in **March 2026**. For early access or specific migration details, please contact your Ripple representative. Use these API operations to manage your identities with **Identity Management v3** (recommended for all new integrations). For more information about identity management, see [Payment identities](/products/payments-direct-2/@v2026.03/api-docs/concepts/payment-identities) and [Financial instruments](/products/payments-direct-2/@v2026.03/api-docs/concepts/financial-instruments). | Operation | Method | Description | | --- | --- | --- | | [Create an identity (v3)](./#operation/createIdentity) | POST | Create a new identity (INDIVIDUAL/BUSINESS; ORIGINATOR/BENEFICIARY). | | [Get a list of identies (v3)](./#operation/getIdentities) | GET | Retrieve a list of identities with optional filters (e.g., `paymentRole`, `identityType`). | | [Get an identity by ID (v3)](./#operation/getIdentityById) | GET | Retrieve a specific identity by `identityId` (latest version by default). | | [Update an identity (v3)](./#operation/putIdentity) | PUT | Update one or more fields; creates a new version. | | [Deactivate an identity (v3)](./#operation/deactivateIdentityV3) | DELETE | Set the identity state to `DEACTIVATED` (cannot be used for new payments). | | [Add a financial instrument (v3)](./#operation/createFinancialInstrument) | POST | Add a financial instrument to an identity. | | [Get a list of financial instruments (v3)](./#operation/getFinancialInstruments) | GET | Get a list of financial instruments for an identity. | | [Get a financial instrument by ID (v3)](./#operation/getFinancialInstrumentById) | GET | Get a specific financial instrument by `financialInstrumentId`. | | [Update a financial instrument (v3)](./#operation/putFinancialInstrument) | PUT | Update a financial instrument by `financialInstrumentId`. | | [Deactivate a financial instrument (v3)](./#operation/deactivateFinancialInstrumentV3) | DELETE | Deactivate a financial instrument by `financialInstrumentId`. | ### Create an identity (v3) - [POST /v3/identities](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/createidentity.md): Create a new payment identity as an ORIGINATOR or BENEFICIARY for either an INDIVIDUAL or BUSINESS. The request body must follow the v3 identity schema and will be validated against corridor rules where applicable. On success, the API returns the new identityId and its initial version. ### Get a list of identities (v3) - [GET /v3/identities](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getidentities.md): Retrieve identities for your tenant with optional filters. Use limit and next-token for pagination. The response includes a data array and an optional nextToken. ### Get an identity by ID (v3) - [GET /v3/identities/{identity-id}](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getidentitybyid.md): Retrieve a specific identity by ID. If version is not provided, the latest version is returned. ### Update an identity (v3) - [PUT /v3/identities/{identity-id}](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/putidentity.md): Update all fields of an existing identity. Supports updates to PII fields and metadata. Each successful PUT creates a new version and preserves prior versions for audit. ### Deactivate an identity (v3) - [DELETE /v3/identities/{identity-id}](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/deactivateidentityv3.md): Deactivate an identity and its financial instruments. Deactivation is permanent and prevents further use in payments. Historical versions remain available for audit. ### Add a financial instrument (v3) - [POST /v3/identities/{identity-id}/financial-instruments](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/createfinancialinstrument.md): Create a financial instrument for the specified identity. The request body must include the payment rail (financialInstrumentType), currency or asset code, and the rail-specific details (for example, US ACH account numbers or a wallet address). In the current release, each identity can have one financial instrument. Future releases will support multiple instruments per identity. ### Get a list of financial instruments of the identity (v3) - [GET /v3/identities/{identity-id}/financial-instruments](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getfinancialinstruments.md): List financial instruments for an identity. ### Get a financial instrument by ID (v3) - [GET /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getfinancialinstrumentbyid.md): Retrieves one financial instrument associated with the specified identity. In the current release, one instrument is retrieved at most because only a single instrument is allowed per identity. ### Update a financial instrument (v3) - [PUT /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/putfinancialinstrument.md): Update editable fields of a financial instrument including rail-specific details and labels. The financialInstrumentType is immutable after creation. ### Deactivate a Financial Instrument (v3) - [DELETE /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/deactivatefinancialinstrumentv3.md): Deactivate a financial instrument of an Identity. Deactivation is permanent and prevents further use in payments. Historical versions remain available for audit. ## Quotes Use these API operations to manage your quotes. | Operation | Method | Description | | --- | --- | --- | | [Create quote collection](./#operation/createQuoteCollection) | POST | Create a collection of quotes. | | [Get quote collection](./#operation/getQuoteCollection) | GET | Get a quote collection by ID. | | [Get a quote](./#operation/getQuote) | GET | Get a specific quote by ID. | ### Create quote collection - [POST /v2/quotes/quote-collection](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/quote/createquotecollection.md): Creates a collection of quotes for a proposed payment. ### Get quote collection - [GET /v2/quotes/quote-collection/{quote-collection-id}](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/quote/getquotecollection.md) ### Get quote - [GET /v2/quotes/{quote-id}](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/quote/getquote.md) ## 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)](./#operation/searchPaymentsV2) | POST | Search for v3 payments based on filtering criteria. | | [Create a payment (v3)](./#operation/createPaymentV2) | POST | Create a v3payment by accepting a quote. | | [Get payment by payment ID (v3)](./#operation/getPaymentByIdV2) | GET | Get a specific v3 payment by payment ID. | | [Get state transitions by payment ID (v3)](./#operation/getPaymentStateTransitionsByIdV2) | GET | Get the state transitions for a specific v3 payment by payment ID. | | [Update payment labels (v3)](./#operation/updatePaymentLabelsV2) | PATCH | Update the labels for a specific v3 payment by payment ID. | ### Search payments (v3) - [POST /v3/payments/filter](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/searchpaymentsv2.md): Search for payments based on filtering criteria. ### Create payment (v3) - [POST /v3/payments](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/createpaymentv2.md): Create a payment ### Get a payment by ID (v3) - [GET /v3/payments/{paymentId}](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/getpaymentbyidv2.md): Gets a payment by ID. ### Get state transitions by payment ID (v3) - [GET /v3/payments/{paymentId}/states](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/getpaymentstatetransitionsbyidv2.md): Gets the state transitions for a payment by ID. ### Update payment labels (v3) - [PATCH /v3/payments/{paymentId}/labels](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/updatepaymentlabelsv2.md): Add or remove labels for a payment. ## Ledger Use these API operation to fetch ledger transactions and check balances. | Operation | Method | Description | | --- | --- | --- | | [Get balances](./#operation/getBalances) | GET | View your existing balances | | [Get ledger transactions](./#operation/getStatementsTransactionsForCustomer) | GET | View your ledger transactions. | ### Get available balances - [GET /v2/balances](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/ledger-public/getbalances.md) ### Get ledger transactions - [GET /v2/ledger-transactions](https://docs.ripple.com/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/ledger-public/getstatementstransactionsforcustomer.md): 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.