# 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:

| <div style="width:90px">Environment</div>  | 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/@l10n/pt-BR/products/payments-direct-2/@v2025.11/api-docs/payments-direct-api/payments-direct-2-api.yaml)

## Authentication

 - [POST /v2/oauth/token](https://docs.ripple.com/pt-br/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
 - [GET /v2/oauth/token/test](https://docs.ripple.com/pt-br/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)

 - [POST /v2/identities](https://docs.ripple.com/pt-br/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
 - [GET /v2/identities](https://docs.ripple.com/pt-br/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 /v2/identities/{identity-id}](https://docs.ripple.com/pt-br/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 /v2/identities/{identity-id}](https://docs.ripple.com/pt-br/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
## Quotes

 - [POST /v2/quotes/quote-collection](https://docs.ripple.com/pt-br/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](../tutorials/create-a-v2-payment.md#create-a-quote-collection).
 - [GET /v2/quotes/quote-collection/{quote-collection-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/quote/getquotecollection.md)
 - [GET /v2/quotes/{quote-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/quote/getquote.md)
## Payments (v2)

 - [POST /v2/payments/filter](https://docs.ripple.com/pt-br/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.
 - [POST /v2/payments](https://docs.ripple.com/pt-br/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](../tutorials/create-a-v2-payment.md). * Learn how to [Create a third-party payment](../tutorials/create-a-v2-third-party-payment.md).
 - [GET /v2/payments/{paymentId}](https://docs.ripple.com/pt-br/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/payments/getpaymentbyid.md): Gets a payment by ID.
 - [GET /v2/payments/{paymentId}/states](https://docs.ripple.com/pt-br/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.
 - [PATCH /v2/payments/{paymentId}/labels](https://docs.ripple.com/pt-br/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

 - [GET /v2/balances](https://docs.ripple.com/pt-br/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/ledger-public/getbalances.md)
 - [GET /v2/ledger-transactions](https://docs.ripple.com/pt-br/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