Search for payments based on filtering criteria.
Payments Direct API (0.0.3)
Use the Payments Direct API to get quotes, create and manage payments, and manage originator and beneficiary identities.
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 |
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.
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:
- Log into the Ripple Payments UI.
- In the left navigation menu, click Settings.
- Under Administration, click API Credentials.
- 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.
- In the upper right corner of the page, click New Credential.
- 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.
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.
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/
https://api.test.ripple.com/
https://api.ripple.com/
Authentication
Use these API operations to manage your authentication tokens.
| Operation | Method | Description |
|---|---|---|
| Request an access token | POST | Request an access token for authentication with Ripple APIs. |
| Test access token | GET | Test if an access token can be used for authentication. |
Identities (v3)
Use these API operations to manage your identities with Identity Management v3 (recommended for all new integrations).
| Operation | Method | Description |
|---|---|---|
| Create an identity (v3) | POST | Create a new identity (INDIVIDUAL/BUSINESS; ORIGINATOR/BENEFICIARY). |
| Get a list of identies (v3) | GET | Retrieve a list of identities with optional filters (e.g., paymentRole, identityType). |
| Get an identity by ID (v3) | GET | Retrieve a specific identity by identityId (latest version by default). |
| Update an identity (v3) | PUT | Update one or more fields; creates a new version. |
| Deactivate an identity (v3) | DELETE | Set the identity state to DEACTIVATED (cannot be used for new payments). |
| Add a financial instrument (v3) | POST | Add a financial instrument to an identity. |
| Get a list of financial instruments (v3) | GET | Get a list of financial instruments for an identity. |
| Get a financial instrument by ID (v3) | GET | Get a specific financial instrument by financialInstrumentId. |
| Update a financial instrument (v3) | PUT | Update a financial instrument by financialInstrumentId. |
| Deactivate a financial instrument (v3) | DELETE | Deactivate a financial instrument by financialInstrumentId. |
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.
| Operation | Method | Description |
|---|---|---|
| Create a new identity (v2) - Legacy | POST | Create a new v2 legacy identity. |
| Get a list of identities (v2) - Legacy | GET | Get a list of existing v2 legacy identities. |
| Get an identity by ID (v2) - Legacy | GET | Get a v2 legacy identity by its unique ID. |
| Delete an identity (v2) - Legacy | DELETE | Deactivate a v2 legacy identity. |
Quotes
Use these API operations to manage your quotes.
| Operation | Method | Description |
|---|---|---|
| Create quote collection | POST | Create a collection of quotes. |
| Get quote collection | GET | Get a quote collection by ID. |
| Get a quote | GET | Get a specific quote by ID. |
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) | POST | Search for v3 payments based on filtering criteria. |
| Create a payment (v3) | POST | Create a v3payment by accepting a quote. |
| Get payment by payment ID (v3) | GET | Get a specific v3 payment by payment ID. |
| Get state transitions by payment ID (v3) | GET | Get the state transitions for a specific v3 payment by payment ID. |
| Update payment labels (v3) | PATCH | Update the labels for a specific v3 payment by payment ID. |
Payments (v2) - Legacy
Use these API operations to manage your v2 legacy payments.
| Operation | Method | Description |
|---|---|---|
| Search payments (v2) - Legacy) | POST | Search for legacy v2 payments based on filtering criteria. |
| Create a payment (v2) - Legacy) | POST | Create a legacy v2 payment by accepting a quote. |
| Get a payment by payment ID (v2) - Legacy | GET | Get a specific legacy v2 payment by payment ID. |
| Get state transitions by payment ID (v2) - Legacy | GET | Get the state transitions for a specific legacy v2 payment by payment ID. |
| Update payment labels (v2) - Legacy | PATCH | Update the labels for a specific legacy v2 payment by payment ID. |
Search payments request
Filter criteria to return desired payment search results.
Specify a list of uuids to search for payment with payment ids equals one from the list
Array of payment states like EXECUTING or COMPLETED.
| Items Enum Value | Description |
|---|---|
| INITIATED | You, the payment originator, have initiated a payment. The payment now has a unique |
| VALIDATING | Ripple validates the payment details and reserves funds from your available balance to complete the payment. |
| TRANSFERRING | The payment is moving through the network to the ultimate beneficiary. The payment amount is debited from your available balance. |
| COMPLETED | The payment is complete and the beneficiary has received the funds. |
| FAILED | The payment failed. The failure reason, if available, is listed in the response. Funds that were previously reserved to complete the payment are released and added back to the available balance. |
| QUOTED | A quote has been created, but you haven't accepted it yet to initiate a payment. Note: This state is not shown as part of the payment detail as the payment doesn't exist yet. |
| RETURNED | The payment is returned. The return reason, if available, is listed in the response. Funds that were previously reserved and debited to complete the payment are returned and added back to the available balance. |
The range type to filter payments on.
| Enum Value | Description |
|---|---|
| PAYMENT_CREATION | Filter results to show payments that were created within the specified time period. |
| PAYMENT_EXPIRY | Filter results to show payments that expired or are set to expire within the specified time period. |
| PAYMENT_STATUS_LAST_UPDATED | Filter results to show payments whose status was last updated within the specified time period. |
Depending on the value of the filterRangeType field, this timestamp returns a list of payments that were created/modified/expired at or before the specified time.
Depending on the value of the filterRangeType field, this timestamp returns a list of payments that were created/modified/expired at or after the specified time.
To get all payments made to one or more beneficiaries, specify the identity ID(s) of those beneficiaries in this field. You can find the identity ID using the GET /identities operation.
Specify an internalId to get payments associated with them. A prefix match will be executed.
To get all payments made to a beneficiary, specify the nickname of that beneficiary in this field. You can find the nickname using the GET /identities operation.
Specify one or more currency codes to get payments where the beneficiary received funds in these currencies.
Application-defined 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 lifetime.
Specify sorting direction and the filtering criterion to sort by.
The field based on which you want to sort the payments in the specified sort order.
| Enum Value | Description |
|---|---|
| internalId | Sort by an internalId of payment |
| paymentState | Sort by payment state |
| sourceCurrency | Sort by source currency of payment |
| sourceAmount | Sort by source amount of payment |
| destinationCurrency | Sort by destination currency of payment |
| destinationCountry | Sort by destination currency of payment |
| destinationAmount | Sort by destination amount of payment |
| initiatedAt | Sort by payment initiated timestamp |
| expiresAt | Sort by payment expiry timestamp |
| lastStateUpdatedAt | Sort by last updated timestamp of payment |
Specify page size and the ID of the last fetched result.
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/payments/filter
- UAT environment with simulated currency
https://api.test.ripple.com/v2/payments/filter
- Production environment
https://api.ripple.com/v2/payments/filter
- curl
- Python
curl -i -X POST \
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/payments/filter \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"filter": {
"paymentIds": [
"aaaaaaaa-1111-bbbb-abab-123412341234"
],
"paymentStates": [
"INITIATED"
],
"filterRangeType": "PAYMENT_CREATION",
"beforeTimestamp": "2024-04-24T14:15:22Z",
"afterTimestamp": "2024-03-24T13:15:22Z",
"beneficiaryIdentityIds": [
"aaaaaaaa-1111-bbbb-abab-123412341234"
],
"internalId": "string",
"beneficiaryIdentityNickname": "Successful business beneficiary",
"destinationCurrencies": [
"string"
],
"paymentLabels": [
"batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
]
},
"sort": {
"sortField": "initiatedAt",
"sortDirection": "DESC"
},
"page": {
"size": 20,
"lastPageToken": "string"
}
}'Payments matching the specified filtering criteria.
Array of Payment objects
The unique ID that identifies this payment. This value is the same as the quote ID.
Transaction hash of the crypto payment on the destination blockchain network
The time at which the payment was initiated, specified in UTC.
The time at which this payment expires, specified in UTC.
The time at which the payment state was last updated for this payment, specified in UTC.
| Enum Value | Description |
|---|---|
| INITIATED | You, the payment originator, have initiated a payment. The payment now has a unique |
| VALIDATING | Ripple validates the payment details and reserves funds from your available balance to complete the payment. |
| TRANSFERRING | The payment is moving through the network to the ultimate beneficiary. The payment amount is debited from your available balance. |
| COMPLETED | The payment is complete and the beneficiary has received the funds. |
| FAILED | The payment failed. The failure reason, if available, is listed in the response. Funds that were previously reserved to complete the payment are released and added back to the available balance. |
| QUOTED | A quote has been created, but you haven't accepted it yet to initiate a payment. Note: This state is not shown as part of the payment detail as the payment doesn't exist yet. |
| RETURNED | The payment is returned. The return reason, if available, is listed in the response. Funds that were previously reserved and debited to complete the payment are returned and added back to the available balance. |
Payment originator and source details.
The unique ID associated with the payment originator's identity record.
The current version of the originator's identity record.
Nickname associated with the originator's identity record.
An ID associated with this payment, if provided by the customer during payment initiation.
The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.
Payment beneficiary and destination details.
The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.
The country where the beneficiary is located specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list. If the beneficiary is an individual, then this value is their country of residence. If the beneficiary is an institution, then this value is their the country of incorporation.
The currency code of the currency in which the beneficiary will receive this payment.
The name of the blockchain network on which the beneficiary will receive this payment.
The unique ID associated with the payment beneficiary's identity record.
The current version of the beneficiary's identity record.
Nickname associated with the beneficiary's identity record.
Foreign Exchange (FX) rate used to calculate the quote.
A summary of fees included in payment quote.
An array of fees that provides a breakdown of how the total fees is calculated for this quote.
Value of the fee when the configured fee unit is applied against the value.
A summary of taxes included in the payment quote.
An array of taxes with details such as tax description, rate, name and tax amount.
GST service fee tax .
The source of cash may be required depending on corridor and payout partner. Valid values for the source of cash vary by corridor.
Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.
A summary of the payment category.
The Ripple payments product used to make this payment.
| Value | Description |
|---|---|
| LICENSED | Identifies a transaction using Ripple Payments Direct. |
Specifies the type of payment you're making as categorized by the identity type of the payment originator and beneficiary.
| Enum Value | Description |
|---|---|
| B2B | Specifies that this payment is made by a business originator to a business beneficiary.
|
| B2C | Specifies that this payment is made by a business originator to an individual beneficiary.
|
Flag to indicate if this payment is initiated on behalf of a third-party originator.
Application-defined 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 lifetime.
Optional, transaction-specific memo carried with the payment for beneficiary reconciliation. Must be UPPERCASE and may include only letters (A-Z), digits (0-9), spaces, and the following punctuation characters: comma (,), period (.), parentheses (()), forward slash (/), and hyphen (-). Not stored in PII; persisted on the payment object and forwarded to compliance and payout partners. Where possible, the memo will also be delivered to the final beneficiary's credit record, but delivery cannot be guaranteed in all cases due to payout partner or downstream constraints. If omitted, Ripple may generate a memo automatically.
Filter criteria to return desired payment search results.
Specify a list of uuids to search for payment with payment ids equals one from the list
Array of payment states like EXECUTING or COMPLETED.
| Items Enum Value | Description |
|---|---|
| INITIATED | You, the payment originator, have initiated a payment. The payment now has a unique |
| VALIDATING | Ripple validates the payment details and reserves funds from your available balance to complete the payment. |
| TRANSFERRING | The payment is moving through the network to the ultimate beneficiary. The payment amount is debited from your available balance. |
| COMPLETED | The payment is complete and the beneficiary has received the funds. |
| FAILED | The payment failed. The failure reason, if available, is listed in the response. Funds that were previously reserved to complete the payment are released and added back to the available balance. |
| QUOTED | A quote has been created, but you haven't accepted it yet to initiate a payment. Note: This state is not shown as part of the payment detail as the payment doesn't exist yet. |
| RETURNED | The payment is returned. The return reason, if available, is listed in the response. Funds that were previously reserved and debited to complete the payment are returned and added back to the available balance. |
The range type to filter payments on.
| Enum Value | Description |
|---|---|
| PAYMENT_CREATION | Filter results to show payments that were created within the specified time period. |
| PAYMENT_EXPIRY | Filter results to show payments that expired or are set to expire within the specified time period. |
| PAYMENT_STATUS_LAST_UPDATED | Filter results to show payments whose status was last updated within the specified time period. |
Depending on the value of the filterRangeType field, this timestamp returns a list of payments that were created/modified/expired at or before the specified time.
Depending on the value of the filterRangeType field, this timestamp returns a list of payments that were created/modified/expired at or after the specified time.
To get all payments made to one or more beneficiaries, specify the identity ID(s) of those beneficiaries in this field. You can find the identity ID using the GET /identities operation.
Specify an internalId to get payments associated with them. A prefix match will be executed.
To get all payments made to a beneficiary, specify the nickname of that beneficiary in this field. You can find the nickname using the GET /identities operation.
Specify one or more currency codes to get payments where the beneficiary received funds in these currencies.
Application-defined 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 lifetime.
Specify sorting direction and the filtering criterion to sort by.
The field based on which you want to sort the payments in the specified sort order.
| Enum Value | Description |
|---|---|
| internalId | Sort by an internalId of payment |
| paymentState | Sort by payment state |
| sourceCurrency | Sort by source currency of payment |
| sourceAmount | Sort by source amount of payment |
| destinationCurrency | Sort by destination currency of payment |
| destinationCountry | Sort by destination currency of payment |
| destinationAmount | Sort by destination amount of payment |
| initiatedAt | Sort by payment initiated timestamp |
| expiresAt | Sort by payment expiry timestamp |
| lastStateUpdatedAt | Sort by last updated timestamp of payment |
Specify page size and the ID of the last fetched result.
{ "data": [ { … } ], "filter": { "paymentIds": [ … ], "paymentStates": [ … ], "filterRangeType": "PAYMENT_CREATION", "beforeTimestamp": "2024-04-24T14:15:22Z", "afterTimestamp": "2024-03-24T13:15:22Z", "beneficiaryIdentityIds": [ … ], "internalId": "string", "beneficiaryIdentityNickname": "Successful business beneficiary", "destinationCurrencies": [ … ], "paymentLabels": [ … ] }, "sort": { "sortField": "initiatedAt", "sortDirection": "DESC" }, "page": { "size": 20, "lastPageToken": "string" } }
create payment request
ID of the quote you want to accept to initiate this payment. Must be in UUID format. This will be used as paymentId.
The identity ID of the payment originator in UUID format. You can find the identity ID using the GET /identities operation.
The identity ID of the payment beneficiary in UUID format. You can find the identity ID using the GET /identities operation.
Customer defined value, such as an invoice number.
Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.
Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.
Application-defined 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 lifetime.
Optional, transaction-specific memo carried with the payment for beneficiary reconciliation. Must be UPPERCASE and may include only letters (A-Z), digits (0-9), spaces, and the following punctuation characters: comma (,), period (.), parentheses (()), forward slash (/), and hyphen (-). Not stored in PII; persisted on the payment object and forwarded to compliance and payout partners. Where possible, the memo will also be delivered to the final beneficiary's credit record, but delivery cannot be guaranteed in all cases due to payout partner or downstream constraints. If omitted, Ripple may generate a memo automatically.
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/payments
- UAT environment with simulated currency
https://api.test.ripple.com/v2/payments
- Production environment
https://api.ripple.com/v2/payments
- curl
- Python
curl -i -X POST \
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/payments \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
"originatorIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630",
"beneficiaryIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630",
"internalId": "Invoice-123",
"purposeCode": "PAYR",
"sourceOfCash": "EMIN",
"paymentLabels": [
"batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
],
"paymentMemo": "ORDER 2025-09-001 PAYMENT"
}'Valid payment
The unique ID that identifies this payment. This value is the same as the quote ID.
Transaction hash of the crypto payment on the destination blockchain network
The time at which the payment was initiated, specified in UTC.
The time at which this payment expires, specified in UTC.
The time at which the payment state was last updated for this payment, specified in UTC.
| Enum Value | Description |
|---|---|
| INITIATED | You, the payment originator, have initiated a payment. The payment now has a unique |
| VALIDATING | Ripple validates the payment details and reserves funds from your available balance to complete the payment. |
| TRANSFERRING | The payment is moving through the network to the ultimate beneficiary. The payment amount is debited from your available balance. |
| COMPLETED | The payment is complete and the beneficiary has received the funds. |
| FAILED | The payment failed. The failure reason, if available, is listed in the response. Funds that were previously reserved to complete the payment are released and added back to the available balance. |
| QUOTED | A quote has been created, but you haven't accepted it yet to initiate a payment. Note: This state is not shown as part of the payment detail as the payment doesn't exist yet. |
| RETURNED | The payment is returned. The return reason, if available, is listed in the response. Funds that were previously reserved and debited to complete the payment are returned and added back to the available balance. |
Payment originator and source details.
The unique ID associated with the payment originator's identity record.
The current version of the originator's identity record.
Nickname associated with the originator's identity record.
An ID associated with this payment, if provided by the customer during payment initiation.
The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.
Payment beneficiary and destination details.
The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.
The country where the beneficiary is located specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list. If the beneficiary is an individual, then this value is their country of residence. If the beneficiary is an institution, then this value is their the country of incorporation.
The currency code of the currency in which the beneficiary will receive this payment.
The name of the blockchain network on which the beneficiary will receive this payment.
The unique ID associated with the payment beneficiary's identity record.
The current version of the beneficiary's identity record.
Nickname associated with the beneficiary's identity record.
Foreign Exchange (FX) rate used to calculate the quote.
A summary of fees included in payment quote.
An array of fees that provides a breakdown of how the total fees is calculated for this quote.
Value of the fee when the configured fee unit is applied against the value.
A summary of taxes included in the payment quote.
An array of taxes with details such as tax description, rate, name and tax amount.
GST service fee tax .
The source of cash may be required depending on corridor and payout partner. Valid values for the source of cash vary by corridor.
Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.
A summary of the payment category.
The Ripple payments product used to make this payment.
| Value | Description |
|---|---|
| LICENSED | Identifies a transaction using Ripple Payments Direct. |
Specifies the type of payment you're making as categorized by the identity type of the payment originator and beneficiary.
| Enum Value | Description |
|---|---|
| B2B | Specifies that this payment is made by a business originator to a business beneficiary.
|
| B2C | Specifies that this payment is made by a business originator to an individual beneficiary.
|
Flag to indicate if this payment is initiated on behalf of a third-party originator.
Application-defined 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 lifetime.
Optional, transaction-specific memo carried with the payment for beneficiary reconciliation. Must be UPPERCASE and may include only letters (A-Z), digits (0-9), spaces, and the following punctuation characters: comma (,), period (.), parentheses (()), forward slash (/), and hyphen (-). Not stored in PII; persisted on the payment object and forwarded to compliance and payout partners. Where possible, the memo will also be delivered to the final beneficiary's credit record, but delivery cannot be guaranteed in all cases due to payout partner or downstream constraints. If omitted, Ripple may generate a memo automatically.
{ "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630", "cryptoTransactionHash": "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb", "initiatedAt": "2019-08-24T14:15:22Z", "expiresAt": "2019-08-24T14:15:22Z", "lastStateUpdatedAt": "2019-08-24T14:15:22Z", "paymentState": "INITIATED", "originator": { "originatorIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630", "originatorIdentityIdVersion": 1, "originatorIdentityNickName": "Successful Business Sender", "internalId": "Invoice-123", "sourceCurrency": "USD", "sourceAmount": 100, "payin": "FUNDED" }, "destination": { "destinationAmount": 1234.111223, "destinationCountry": "US", "destinationCurrency": "USD", "destinationBlockchainNetwork": "Ethereum, TRON", "beneficiaryIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630", "beneficiaryIdentityVersion": 1, "beneficiaryIdentityNickName": "Successful business beneficiary", "payout": "BANK" }, "adjustedExchangeRate": { "adjustedRate": 2 }, "fees": [ { … } ], "taxes": [ { … } ], "sourceOfCash": "EMIN", "purposeCode": "PAYR", "transactionDetails": { "paymentProduct": "string", "flowType": "B2B", "thirdPartyPayment": false, "businessUseCase": "ON_RAMP" }, "paymentLabels": [ "batchId=aaaaaaaa-1111-bbbb-abab-123412341234" ], "paymentMemo": "ORDER 2025-09-001 PAYMENT" }
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/payments/{paymentId}
- UAT environment with simulated currency
https://api.test.ripple.com/v2/payments/{paymentId}
- Production environment
https://api.ripple.com/v2/payments/{paymentId}
- curl
- Python
curl -i -X GET \
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/payments/7ea3399c-1234-5678-8d8f-d320ea406630 \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Successfully fetched payment details.
The unique ID that identifies this payment. This value is the same as the quote ID.
Transaction hash of the crypto payment on the destination blockchain network
The time at which the payment was initiated, specified in UTC.
The time at which this payment expires, specified in UTC.
The time at which the payment state was last updated for this payment, specified in UTC.
| Enum Value | Description |
|---|---|
| INITIATED | You, the payment originator, have initiated a payment. The payment now has a unique |
| VALIDATING | Ripple validates the payment details and reserves funds from your available balance to complete the payment. |
| TRANSFERRING | The payment is moving through the network to the ultimate beneficiary. The payment amount is debited from your available balance. |
| COMPLETED | The payment is complete and the beneficiary has received the funds. |
| FAILED | The payment failed. The failure reason, if available, is listed in the response. Funds that were previously reserved to complete the payment are released and added back to the available balance. |
| QUOTED | A quote has been created, but you haven't accepted it yet to initiate a payment. Note: This state is not shown as part of the payment detail as the payment doesn't exist yet. |
| RETURNED | The payment is returned. The return reason, if available, is listed in the response. Funds that were previously reserved and debited to complete the payment are returned and added back to the available balance. |
Payment originator and source details.
The unique ID associated with the payment originator's identity record.
The current version of the originator's identity record.
Nickname associated with the originator's identity record.
An ID associated with this payment, if provided by the customer during payment initiation.
The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.
Payment beneficiary and destination details.
The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.
The country where the beneficiary is located specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list. If the beneficiary is an individual, then this value is their country of residence. If the beneficiary is an institution, then this value is their the country of incorporation.
The currency code of the currency in which the beneficiary will receive this payment.
The name of the blockchain network on which the beneficiary will receive this payment.
The unique ID associated with the payment beneficiary's identity record.
The current version of the beneficiary's identity record.
Nickname associated with the beneficiary's identity record.
Foreign Exchange (FX) rate used to calculate the quote.
A summary of fees included in payment quote.
An array of fees that provides a breakdown of how the total fees is calculated for this quote.
Value of the fee when the configured fee unit is applied against the value.
A summary of taxes included in the payment quote.
An array of taxes with details such as tax description, rate, name and tax amount.
GST service fee tax .
Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.
Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.
A summary of the payment category.
The Ripple payments product used to make this payment.
| Value | Description |
|---|---|
| LICENSED | Identifies a transaction using Ripple Payments Direct. |
Specifies the type of payment you're making as categorized by the identity type of the payment originator and beneficiary.
| Enum Value | Description |
|---|---|
| B2B | Specifies that this payment is made by a business originator to a business beneficiary.
|
| B2C | Specifies that this payment is made by a business originator to an individual beneficiary.
|
Flag to indicate if this payment is initiated on behalf of a third-party originator.
A high-level categorization of the error, indicating the type of issue that occurred
A more detailed explanation of the error, potentially including information about what caused the error and the next steps
Application-defined 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 lifetime.
Optional, transaction-specific memo carried with the payment for beneficiary reconciliation. Must be UPPERCASE and may include only letters (A-Z), digits (0-9), spaces, and the following punctuation characters: comma (,), period (.), parentheses (()), forward slash (/), and hyphen (-). Not stored in PII; persisted on the payment object and forwarded to compliance and payout partners. Where possible, the memo will also be delivered to the final beneficiary's credit record, but delivery cannot be guaranteed in all cases due to payout partner or downstream constraints. If omitted, Ripple may generate a memo automatically.
{ "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630", "cryptoTransactionHash": "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb", "initiatedAt": "2019-08-24T14:15:22Z", "expiresAt": "2019-08-24T14:15:22Z", "lastStateUpdatedAt": "2019-08-24T14:15:22Z", "paymentState": "INITIATED", "originator": { "originatorIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630", "originatorIdentityIdVersion": 1, "originatorIdentityNickName": "Successful Business Sender", "internalId": "Invoice-123", "sourceCurrency": "USD", "sourceAmount": 100, "payin": "FUNDED" }, "destination": { "destinationAmount": 1234.111223, "destinationCountry": "US", "destinationCurrency": "USD", "destinationBlockchainNetwork": "Ethereum, TRON", "beneficiaryIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630", "beneficiaryIdentityVersion": 1, "beneficiaryIdentityNickName": "Successful business beneficiary", "payout": "BANK" }, "adjustedExchangeRate": { "adjustedRate": 2 }, "fees": [ { … } ], "taxes": [ { … } ], "sourceOfCash": "EMIN", "purposeCode": "PAYR", "transactionDetails": { "paymentProduct": "string", "flowType": "B2B", "thirdPartyPayment": false, "businessUseCase": "ON_RAMP" }, "errors": [ { … } ], "paymentLabels": [ "batchId=aaaaaaaa-1111-bbbb-abab-123412341234" ], "paymentMemo": "ORDER 2025-09-001 PAYMENT" }
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/payments/{paymentId}/states
- UAT environment with simulated currency
https://api.test.ripple.com/v2/payments/{paymentId}/states
- Production environment
https://api.ripple.com/v2/payments/{paymentId}/states
- curl
- Python
curl -i -X GET \
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/payments/7ea3399c-1234-5678-8d8f-d320ea406630/states \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Successfully fetched payment state transitions.
| Enum Value | Description |
|---|---|
| INITIATED | You, the payment originator, have initiated a payment. The payment now has a unique |
| VALIDATING | Ripple validates the payment details and reserves funds from your available balance to complete the payment. |
| TRANSFERRING | The payment is moving through the network to the ultimate beneficiary. The payment amount is debited from your available balance. |
| COMPLETED | The payment is complete and the beneficiary has received the funds. |
| FAILED | The payment failed. The failure reason, if available, is listed in the response. Funds that were previously reserved to complete the payment are released and added back to the available balance. |
| QUOTED | A quote has been created, but you haven't accepted it yet to initiate a payment. Note: This state is not shown as part of the payment detail as the payment doesn't exist yet. |
| RETURNED | The payment is returned. The return reason, if available, is listed in the response. Funds that were previously reserved and debited to complete the payment are returned and added back to the available balance. |
| Enum Value | Description |
|---|---|
| INITIATED | You, the payment originator, have initiated a payment. The payment now has a unique |
| VALIDATING | Ripple validates the payment details and reserves funds from your available balance to complete the payment. |
| TRANSFERRING | The payment is moving through the network to the ultimate beneficiary. The payment amount is debited from your available balance. |
| COMPLETED | The payment is complete and the beneficiary has received the funds. |
| FAILED | The payment failed. The failure reason, if available, is listed in the response. Funds that were previously reserved to complete the payment are released and added back to the available balance. |
| QUOTED | A quote has been created, but you haven't accepted it yet to initiate a payment. Note: This state is not shown as part of the payment detail as the payment doesn't exist yet. |
| RETURNED | The payment is returned. The return reason, if available, is listed in the response. Funds that were previously reserved and debited to complete the payment are returned and added back to the available balance. |
{ "stateTransitions": [ { … } ] }
Labels to add to or remove from the payment.
Application-defined 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 lifetime.
Application-defined 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 lifetime.
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/payments/{paymentId}/labels
- UAT environment with simulated currency
https://api.test.ripple.com/v2/payments/{paymentId}/labels
- Production environment
https://api.ripple.com/v2/payments/{paymentId}/labels
- curl
- Python
curl -i -X PATCH \
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/payments/7ea3399c-1234-5678-8d8f-d320ea406630/labels \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"labelsToAdd": [
"batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
],
"labelsToRemove": [
"batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
]
}'Successfully updated the payment labels.
Application-defined 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 lifetime.
{ "labels": [ "batchId=aaaaaaaa-1111-bbbb-abab-123412341234" ] }
Ledger
Use these API operation to fetch ledger transactions and check balances.
| Operation | Method | Description |
|---|---|---|
| Get balances | GET | View your existing balances |
| Get ledger transactions | GET | View your ledger transactions. |