# 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 {% $env.PUBLIC_VAR_RNH %}. 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/authenticate) operation. ### Request an access token To get an access token, use the [Request an access token](#operation/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: 2025.11 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/@v2025.11/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/v2025.11/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. 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 Payments Direct | ### Test access token - [GET /v2/oauth/token/test](https://docs.ripple.com/products/payments-direct-2/v2025.11/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 (v2) 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**. **Before you create identities:** `POST /v2/identities` matches on a party ID taken from `piiData`. A request that matches an existing identity adds a version to it instead of creating a second one, and the new version is built from the request body in full, replacing `piiData` and `nickName` rather than merging them. See [Create a new identity (v2)](#operation/createIdentityV2) and [Identity matching (v2)](../concepts/identity-matching.md). | Operation | Method | Description | | --- | --- | --- | | [Create a new identity (v2)](#operation/createIdentityV2) | POST | Create a new v2 identity. | | [Get a list of identities (v2)](#operation/getIdentitiesV2) | GET | Get a list of existing v2 identities. | | [Get an identity by ID (v2)](#operation/getIdentityByIdV2) | GET | Get a v2 identity by its unique ID. | | [Delete an identity (v2)](#operation/deactivateIdentityV2) | DELETE | Deactivate a v2 identity. | ### Create a new identity (v2) - Legacy - [POST /v2/identities](https://docs.ripple.com/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/identitiesv2/createidentityv2.md): Create a new identity, or add a new version to an existing one when the request matches. Before writing, the service derives a match key from piiData: OrgId.Othr.Id when useCaseType is BUSINESS, or PrvtId.Othr.Id when it is INDIVIDUAL. The value is normalized (ASCII whitespace and punctuation removed, then uppercased) and hashed per tenant. If an active identity with the same key and identityType already exists, the request does not create a new identity. It writes the new version from the request body in full (piiData and nickName are replaced, not merged) and returns 201 with the existing identityId and its version incremented. If there is no match, a new identity is created at version 1. If piiData contains no value at that path, no match key is recorded and the request always creates a new identity. Whether the field is present depends on the data requirements for the corridor, currency, use case, and payout method you are sending on. Two identities cannot share the same match key and identityType within a tenant. To register a second bank account for the same party, deactivate the existing identity first, which is permanent, or use the v3 identities API, which does not match on OrgId.Othr.Id or PrvtId.Othr.Id. v3 keys identities on a client-supplied internalId and rejects a create whose internalId already belongs to an active identity with 409, so two accounts for one party are created with distinct internalId values. For the full behavior, including how to hold two bank accounts for one payee and what happens when two payees share an ID number, see Identity matching (v2). ### Get a list of identities (v2) - Legacy - [GET /v2/identities](https://docs.ripple.com/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/identitiesv2/getidentitiesv2.md): 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. ### Get an identity by ID (v2) - Legacy - [GET /v2/identities/{identity-id}](https://docs.ripple.com/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/identitiesv2/getidentitybyidv2.md): Retrieve a specific identity by ID. If version is not provided, the latest version is returned. ### Delete an identity (v2) - Legacy - [DELETE /v2/identities/{identity-id}](https://docs.ripple.com/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/identitiesv2/deactivateidentityv2.md): Deactivate an identity. Deactivation is permanent and prevents further use in payments. Historical versions remain available for audit. Deactivation also releases the identity's match key, so a later POST /v2/identities with the same OrgId.Othr.Id or PrvtId.Othr.Id and identityType creates a new identity rather than adding a version. ## 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/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/quote/createquotecollection.md): Creates a collection of quotes for a proposed payment. Tutorials * Learn how to Create a quote. ### Get quote collection - [GET /v2/quotes/quote-collection/{quote-collection-id}](https://docs.ripple.com/products/payments-direct-2/v2025.11/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/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/quote/getquote.md) ## Payments (v2) Use these API operations to manage your v2 payments. | Operation | Method | Description | | --- | --- | --- | | [Search payments (v2))](#operation/searchPayments) | POST | Search for v2 payments based on filtering criteria. | | [Create a payment (v2))](#operation/createPayment) | POST | Create a v2 payment by accepting a quote. | | [Get a payment by payment ID (v2)](#operation/getPaymentById) | GET | Get a specific v2 payment by payment ID. | | [Get state transitions by payment ID (v2)](#operation/getPaymentStateTransitionsById) | GET | Get the state transitions for a specific v2 payment by payment ID. | | [Update payment labels (v2)](#operation/updatePaymentLabels) | PATCH | Update the labels for a specific v2 payment by payment ID. | ### Search payments - [POST /v2/payments/filter](https://docs.ripple.com/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/payments/searchpayments.md): Search for payments based on filtering criteria. ### Create payment - [POST /v2/payments](https://docs.ripple.com/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/payments/createpayment.md): Create a payment Tutorials * Learn how to Create a payment. * Learn how to Create a third-party payment. ### Get a payment by ID - [GET /v2/payments/{paymentId}](https://docs.ripple.com/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/payments/getpaymentbyid.md): Gets a payment by ID. ### Get state transitions by payment ID - [GET /v2/payments/{paymentId}/states](https://docs.ripple.com/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/payments/getpaymentstatetransitionsbyid.md): Gets the state transitions for a payment by ID. ### Update payment labels - [PATCH /v2/payments/{paymentId}/labels](https://docs.ripple.com/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/payments/updatepaymentlabels.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/v2025.11/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/v2025.11/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.