# 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](#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: 2026.04 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/@v2026.04/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/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/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 - [POST /v3/identities](https://docs.ripple.com/pt-br/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 r - [GET /v3/identities](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getidentities.md): Retrieve identities for your organization with optional filters. Use `limit` and `next-token` for pagination. The response includes a `data` array and an optional `nextToken`. - [GET /v3/identities/{identity-id}](https://docs.ripple.com/pt-br/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. - [PUT /v3/identities/{identity-id}](https://docs.ripple.com/pt-br/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. - [DELETE /v3/identities/{identity-id}](https://docs.ripple.com/pt-br/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. - [GET /v3/identities/by-internal-id/{internal-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getidentitybyinternalid.md): Retrieve a specific identity by its internal ID. **Behavior:** - Only returns identities in the `ACTIVE` state. Deactivated identities will result in an error. - Always returns the latest version of t - [POST /v3/identities/{identity-id}/financial-instruments](https://docs.ripple.com/pt-br/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, - [GET /v3/identities/{identity-id}/financial-instruments](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/identitiesv3/getfinancialinstruments.md): List financial instruments for an identity. - [GET /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}](https://docs.ripple.com/pt-br/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. - [PUT /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}](https://docs.ripple.com/pt-br/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. - [DELETE /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}](https://docs.ripple.com/pt-br/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 - [POST /v3/quotes/quote-collection](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/quote/createquotecollectionv2.md): Creates a collection of quotes for a proposed payment, one for each payment rail available for the corridor. A payment rail Ripple can't price is left out. Each quote has its own `quoteId`, `paymentRa - [GET /v3/quotes/quote-collection/{quote-collection-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/quote/getquotecollectionv2.md): Retrieve a previously created quote collection by its unique identifier. Use this endpoint to check the status of quotes (ACTIVE or EXPIRED) and retrieve quote details needed for payment creation. - [GET /v3/quotes/{quote-id}](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/quote/getquotev2.md): Retrieve a specific quote by its unique identifier. Use this endpoint to: - Verify quote details before creating a payment - Check if a quote is still active (not expired) - Retrieve the `quoteId` nee ## Payments - [POST /v3/payments/filter](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/searchpaymentsv2.md): Returns a paginated list of payments matching the specified filters. You can filter by status, date range, destination country, currency, or custom labels. - [POST /v3/payments](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/createpaymentv2.md): Initiates a new cross-border payment. Payments are processed asynchronously. Use **Get a payment by ID** to poll for status updates, or **Get state transitions** to view the full status history. - [GET /v3/payments/{paymentId}](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/getpaymentbyidv2.md): Returns the current status and full details of a payment, including amounts, beneficiary information, and the associated quote. - [GET /v3/payments/{paymentId}/states](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/getpaymentstatetransitionsbyidv2.md): Returns the complete state transition history for a payment, including each status change and its timestamp. Use this to audit payment progress or debug processing issues. - [PATCH /v3/payments/{paymentId}/labels](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/updatepaymentlabelsv2.md): Add or remove labels for grouping and categorizing payments (e.g., campaign IDs, workflow tags, or batch identifiers). Labels are optional and mutable; they can be added or removed over the payment's ## Ledger - [GET /v2/balances](https://docs.ripple.com/pt-br/products/payments-direct-2/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/api-docs/payments-direct-api/payments-direct-2-api/ledger-public/getstatementstransactionsforcustomer.md): Retrieve a paginated list of ledger transactions within a specified date and time range. This endpoint returns detailed transaction data, including amounts, references, operations, and running balance