Payments Direct API (0.0.3)

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 {{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.

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:

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.

Request an access token

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.

Overview

License

Apache 2.0

Servers

Mock server

https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/

UAT environment with simulated currency

https://api.test.ripple.com/

Production environment

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.

Operations

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`.

Operations

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.

Operations

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.

Operations

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.

Operations

Search payments (v3)

Request

Search for payments based on filtering criteria.

Security

Bearer

Bodyapplication/jsonrequired

Search payments request

filterobject

Filter criteria to return desired payment search results.

paymentIdsArray of strings(uuid)

Specify a list of uuids to search for payment with payment ids equals one from the list

Example: ["aaaaaaaa-1111-bbbb-abab-123412341234"]

paymentStatesArray of strings

Array of payment states like EXECUTING or COMPLETED.

Items Enum Value	Description
QUOTED	A quote has been created, but the payment has not yet been initiated.
INITIATED	The payment has been submitted and is awaiting validation.
VALIDATING	Ripple is validating the payment details and reserving funds from the originator’s available balance.
TRANSFERRING	The payment is being processed and funds are moving through the network toward the beneficiary.
COMPLETED	The payment has completed and the beneficiary has received the funds.
FAILED	The payment could not be completed. 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.
RETURNED	The payment was returned by a downstream institution. 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.
DECLINED	The payment was declined due to user input errors or business rule violations. The decline 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.

Example: ["INITIATED"]

filterRangeTypestring

The type of timestamp to use when filtering payments by a date and time range. Supported values include: - PAYMENT_CREATION - PAYMENT_EXPIRY - PAYMENT_STATUS_LAST_UPDATED If another value is provided, the filter is rejected with a validation error.

Enum Value	Description
PAYMENT_CREATION	Filter by the time a payment was created
PAYMENT_EXPIRY	Filter by the time a payment is scheduled to expire
PAYMENT_STATUS_LAST_UPDATED	Filter by the time a payment state was last updated

Example: "PAYMENT_CREATION"

beforeTimestampstring(date-time)

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.

Example: "2024-04-24T14:15:22Z"

afterTimestampstring(date-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.

Example: "2024-03-24T13:15:22Z"

beneficiaryIdentityIdsArray of strings

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.

Example: ["aaaaaaaa-1111-bbbb-abab-123412341234"]

internalIdstring<= 36 characters

Specify an internalId to get payments associated with them. A prefix match will be executed.

beneficiaryIdentityNicknamestring<= 100 characters

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.

Example: "Successful business beneficiary"

destinationCurrenciesArray of strings^[A-Z]{3,5}$

Specify one or more currency codes to get payments where the beneficiary received funds in these currencies.

paymentLabelsArray of strings<= 10 items

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.

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

sortobject

Defines the sorting parameters for listing payments, including the field and sort direction.

sortFieldstring

The field to use when sorting payments in the requested sort order.

Currently supported values include:

internalId
paymentState
sourceCurrency
sourceAmount
destinationCurrency
destinationCountry
destinationAmount
initiatedAt
expiresAt
lastStateUpdatedAt
paymentLabel

If an unsupported value is provided, the request fails with a validation error.

Default "initiatedAt"

Enum Value	Description
internalId	Internal identifier of a payment
paymentState	Current state of a payment
sourceCurrency	Source currency of a payment
sourceAmount	Source amount of a payment
destinationCurrency	Destination currency of a payment
destinationCountry	Destination country of a payment
destinationAmount	Destination amount of a payment
initiatedAt	Timestamp when a payment was initiated
expiresAt	Timestamp when a payment will expire
lastStateUpdatedAt	Timestamp when a payment state was last updated

Example: "initiatedAt"

sortDirectionstring

Indicates whether results are sorted in ascending (ASC) or descending (DESC) order.

Default "DESC"

Enum Value	Description
ASC	Sort results in ascending order.
DESC	Sort results in descending order.

Example: "DESC"

pageobject

Specify page size and the ID of the last fetched result.

sizeinteger[ 1 .. 100 ]

Size of the page

Default 20

Example: 20

lastPageTokenstring

The unique reference ID of the last fetched item. To retrieve subsequent item(s) if any, specify this value as the value of the Page.list field in the POST /payments/filter operation request body.

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/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"
    }
  }'

Responses

Payments matching the specified filtering criteria.

Bodyapplication/json

dataArray of objects

Array of Payment objects

paymentIdstring(uuid)<= 36 charactersrequired

The unique ID that identifies this payment. This value is the same as the quote ID.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

cryptoTransactionHashstring

Transaction hash of the crypto payment on the destination blockchain network

Example: "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb"

initiatedAtstring(date-time)

The time at which the payment was initiated, specified in UTC.

Example: "2019-08-24T14:15:22Z"

expiresAtstring(date-time)

The time at which this payment expires, specified in UTC.

Example: "2019-08-24T14:15:22Z"

lastStateUpdatedAtstring(date-time)

The time at which the payment state was last updated for this payment, specified in UTC.

Example: "2019-08-24T14:15:22Z"

paymentStatestringrequired

Current state of a payment.

The payment lifecycle currently uses the following values:

QUOTED
INITIATED
VALIDATING
TRANSFERRING
COMPLETED
FAILED
RETURNED
DECLINED

Additional states may be introduced in the future without breaking existing integrations.

Enum Value	Description
QUOTED	A quote has been created, but the payment has not yet been initiated.
INITIATED	The payment has been submitted and is awaiting validation.
VALIDATING	Ripple is validating the payment details and reserving funds from the originator’s available balance.
TRANSFERRING	The payment is being processed and funds are moving through the network toward the beneficiary.
COMPLETED	The payment has completed and the beneficiary has received the funds.
FAILED	The payment could not be completed. 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.
RETURNED	The payment was returned by a downstream institution. 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.
DECLINED	The payment was declined due to user input errors or business rule violations. The decline 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.

Example: "INITIATED"

originatorobject

Payment originator and source details.

originatorIdentityIdstring

The unique ID associated with the payment originator's identity record.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

originatorIdentityIdVersioninteger

The current version of the originator's identity record.

Example: 1

originatorIdentityNickNamestring<= 100 characters

Nickname associated with the originator's identity record.

Example: "Successful Business Sender"

internalIdstring<= 35 characters

An ID associated with this payment, if provided by the customer during payment initiation.

Example: "Invoice-123"

sourceCurrencystring<= 5 characters^[A-Z]{3,5}$

originator's currency

Example: "USD"

sourceAmountnumber(double)

The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.

Example: 100

payinstring

Details about how this payment is funded.

Example: "FUNDED"

destinationobject

beneficiaryFinancialInstrumentIdstring

The financial instrument ID, the identity ID of the payment beneficiary is related to.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

destinationAmountnumber(double)

The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.

Example: 1234.111223

destinationCountrystring<= 2 characters^[A-Z]{2}$

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.

Example: "US"

destinationCurrencystring<= 5 characters^[A-Z]{3,5}$

The currency code of the currency in which the beneficiary will receive this payment.

Example: "USD"

destinationBlockchainNetworkstring[ 1 .. 20 ] characters

The name of the blockchain network on which the beneficiary will receive this payment.

Example: "Ethereum, TRON"

beneficiaryIdentityIdstring

The unique ID associated with the payment beneficiary's identity record.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

beneficiaryIdentityVersioninteger

The current version of the beneficiary's identity record.

Example: 1

beneficiaryIdentityNickNamestring<= 100 characters

Nickname associated with the beneficiary's identity record.

Example: "Successful business beneficiary"

payoutstring

The payout category for this payment.

Example: "BANK"

adjustedExchangeRateobject

Foreign Exchange (FX) rate used to calculate the quote.

adjustedRatenumber(double)

Value of the Foreign Exchange (FX) rate.

Example: 2

feesArray of objects

A summary of fees included in the payment quote.

totalFeenumber(double)

The value of the total fee included in this quote.

Example: 12.23

feeCurrencystring^[a-zA-Z]{3,5}$

The currency in which fees are charged.

Example: "USD"

feeBreakdownArray of objects

An array of fees that provides a breakdown of how the total fees is calculated for this quote.

calculatedFeenumber(double)

Value of the fee when the configured fee unit is applied against the value.

Example: 2.43

feeNamestring[ 1 .. 128 ] characters

The name of the fee.

Example: "Service fee"

feeDescriptionstring[ 1 .. 256 ] characters

Description of the fee.

Example: "The service fee charged for this transaction."

taxesArray of objects

A summary of taxes included in the payment quote.

totalTaxesnumber(double)

The value of the total taxes included in this quote.

Example: 5.12

taxCurrencystring^[a-zA-Z]{3,5}$

The currency in which taxes are charged.

Example: "USD"

taxBreakdownArray of objects

An array of taxes with details such as tax description, rate, name and tax amount.

taxAmountnumber(double)

tax amount for this tax line item.

Example: 2.43

taxNamestring[ 1 .. 128 ] characters

The name of the tax.

Example: "ISS/ VAT/ GST etc"

taxDescriptionstring[ 1 .. 256 ] characters

GST service fee tax .

Example: "The service fee tax charged for this transaction."

taxRatenumber(double)

The tax rate applied to calculate the tax amount.

Example: 5

sourceOfCashstring

Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.

Example: "EMIN"

purposeCodestring

Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.

Example: "PAYR"

transactionDetailsobject

A summary of the payment category.

paymentProductstring or null

The Ripple payments product used to make this payment.

Value	Description
LICENSED	Identifies a transaction using Ripple Payments Direct.

flowTypestring or null

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. Identification of third-party payment: If the `thirdPartyPayment` property is `true`, it indicates that you're making this payment on behalf of a business originator. If the `thirdPartyPayment` property is `false`, it indicates that you are the business originator making this payment.
B2C	Specifies that this payment is made by a business originator to an individual beneficiary. Identification of third-party payment: If the `thirdPartyPayment` property is `true`, it indicates that you're making this payment on behalf of a business originator. If the `thirdPartyPayment` property is `false`, it indicates that you are the business originator making this payment.

thirdPartyPaymentboolean or null

Flag to indicate if this payment is initiated on behalf of a third-party originator.

Example: false

businessUseCasestring or null

Indicates the type of payment you're making.

Value	Description
FIAT_TRANSFER	Indicates fiat source currency to fiat destination.

paymentLabelsArray of strings<= 10 items

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

receiverRelationshipstring

The relationship to the debtor.

Example: "SUBS"

paymentMemostring<= 140 characters^[A-Z0-9 ,.()/-]*$

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.

Example: "ORDER 2025-09-001 PAYMENT"

filterobject

Filter criteria to return desired payment search results.

paymentIdsArray of strings(uuid)

Specify a list of uuids to search for payment with payment ids equals one from the list

Example: ["aaaaaaaa-1111-bbbb-abab-123412341234"]

paymentStatesArray of strings

Array of payment states like EXECUTING or COMPLETED.

Items Enum Value	Description
QUOTED	A quote has been created, but the payment has not yet been initiated.
INITIATED	The payment has been submitted and is awaiting validation.
VALIDATING	Ripple is validating the payment details and reserving funds from the originator’s available balance.
TRANSFERRING	The payment is being processed and funds are moving through the network toward the beneficiary.
COMPLETED	The payment has completed and the beneficiary has received the funds.
FAILED	The payment could not be completed. 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.
RETURNED	The payment was returned by a downstream institution. 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.
DECLINED	The payment was declined due to user input errors or business rule violations. The decline 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.

Example: ["INITIATED"]

filterRangeTypestring

Enum Value	Description
PAYMENT_CREATION	Filter by the time a payment was created
PAYMENT_EXPIRY	Filter by the time a payment is scheduled to expire
PAYMENT_STATUS_LAST_UPDATED	Filter by the time a payment state was last updated

Example: "PAYMENT_CREATION"

beforeTimestampstring(date-time)

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.

Example: "2024-04-24T14:15:22Z"

afterTimestampstring(date-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.

Example: "2024-03-24T13:15:22Z"

beneficiaryIdentityIdsArray of strings

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.

Example: ["aaaaaaaa-1111-bbbb-abab-123412341234"]

internalIdstring<= 36 characters

Specify an internalId to get payments associated with them. A prefix match will be executed.

beneficiaryIdentityNicknamestring<= 100 characters

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.

Example: "Successful business beneficiary"

destinationCurrenciesArray of strings^[A-Z]{3,5}$

Specify one or more currency codes to get payments where the beneficiary received funds in these currencies.

paymentLabelsArray of strings<= 10 items

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

sortobject

Defines the sorting parameters for listing payments, including the field and sort direction.

sortFieldstring

The field to use when sorting payments in the requested sort order.

Currently supported values include:

internalId
paymentState
sourceCurrency
sourceAmount
destinationCurrency
destinationCountry
destinationAmount
initiatedAt
expiresAt
lastStateUpdatedAt
paymentLabel

If an unsupported value is provided, the request fails with a validation error.

Default "initiatedAt"

Enum Value	Description
internalId	Internal identifier of a payment
paymentState	Current state of a payment
sourceCurrency	Source currency of a payment
sourceAmount	Source amount of a payment
destinationCurrency	Destination currency of a payment
destinationCountry	Destination country of a payment
destinationAmount	Destination amount of a payment
initiatedAt	Timestamp when a payment was initiated
expiresAt	Timestamp when a payment will expire
lastStateUpdatedAt	Timestamp when a payment state was last updated

Example: "initiatedAt"

sortDirectionstring

Indicates whether results are sorted in ascending (ASC) or descending (DESC) order.

Default "DESC"

Enum Value	Description
ASC	Sort results in ascending order.
DESC	Sort results in descending order.

Example: "DESC"

pageobject

Specify page size and the ID of the last fetched result.

sizeinteger[ 1 .. 100 ]

Size of the page

Default 20

Example: 20

lastPageTokenstring

Response

application/json

{
  "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 (v3)

Request

Create a payment

Tutorial

Learn how to Create a payment.

Security

Bearer

Bodyapplication/jsonrequired

create payment request

quoteIdstring(uuid)required

ID of the quote you want to accept to initiate this payment. Must be in UUID format. This will be used as paymentId.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

originatorIdentityIdstring

The identity ID of the payment originator. You can find the identity ID using the GET /identities operation.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

beneficiaryIdentityIdstringrequired

The identity ID of the payment beneficiary. You can find the identity ID using the GET /identities operation.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

internalIdstring<= 36 characters

Customer defined value, such as an invoice number.

Example: "Invoice-123"

purposeCodestring

Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.

Example: "PAYR"

sourceOfCashstring

Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.

Example: "EMIN"

paymentLabelsArray of strings<= 10 items

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

beneficiaryFinancialInstrumentIdstringrequired

The financial instrument ID associated with a payment beneficiary’s identity. This value must reference a financial instrument created for the same beneficiary identity using Identity Management v3. Use the financialInstrumentId returned when you create or fetch the beneficiary’s payout instrument.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

receiverRelationshipstring

The relationship to the debtor.

Example: "SUBS"

paymentMemostring<= 140 characters^[A-Z0-9 ,.()/-]*$

Example: "ORDER 2025-09-001 PAYMENT"

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/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"
    ],
    "beneficiaryFinancialInstrumentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    "receiverRelationship": "SUBS",
    "paymentMemo": "ORDER 2025-09-001 PAYMENT"
  }'

Responses

Valid payment

Bodyapplication/json

paymentIdstring(uuid)<= 36 charactersrequired

The unique ID that identifies this payment. This value is the same as the quote ID.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

cryptoTransactionHashstring

Transaction hash of the crypto payment on the destination blockchain network

Example: "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb"

initiatedAtstring(date-time)

The time at which the payment was initiated, specified in UTC.

Example: "2019-08-24T14:15:22Z"

expiresAtstring(date-time)

The time at which this payment expires, specified in UTC.

Example: "2019-08-24T14:15:22Z"

lastStateUpdatedAtstring(date-time)

The time at which the payment state was last updated for this payment, specified in UTC.

Example: "2019-08-24T14:15:22Z"

paymentStatestringrequired

Current state of a payment.

The payment lifecycle currently uses the following values:

QUOTED
INITIATED
VALIDATING
TRANSFERRING
COMPLETED
FAILED
RETURNED
DECLINED

Additional states may be introduced in the future without breaking existing integrations.

Enum Value	Description
QUOTED	A quote has been created, but the payment has not yet been initiated.
INITIATED	The payment has been submitted and is awaiting validation.
VALIDATING	Ripple is validating the payment details and reserving funds from the originator’s available balance.
TRANSFERRING	The payment is being processed and funds are moving through the network toward the beneficiary.
COMPLETED	The payment has completed and the beneficiary has received the funds.
FAILED	The payment could not be completed. 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.
RETURNED	The payment was returned by a downstream institution. 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.
DECLINED	The payment was declined due to user input errors or business rule violations. The decline 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.

Example: "INITIATED"

originatorobject

Payment originator and source details.

originatorIdentityIdstring

The unique ID associated with the payment originator's identity record.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

originatorIdentityIdVersioninteger

The current version of the originator's identity record.

Example: 1

originatorIdentityNickNamestring<= 100 characters

Nickname associated with the originator's identity record.

Example: "Successful Business Sender"

internalIdstring<= 35 characters

An ID associated with this payment, if provided by the customer during payment initiation.

Example: "Invoice-123"

sourceCurrencystring<= 5 characters^[A-Z]{3,5}$

originator's currency

Example: "USD"

sourceAmountnumber(double)

The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.

Example: 100

payinstring

Details about how this payment is funded.

Example: "FUNDED"

destinationobject

beneficiaryFinancialInstrumentIdstring

The financial instrument ID, the identity ID of the payment beneficiary is related to.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

destinationAmountnumber(double)

The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.

Example: 1234.111223

destinationCountrystring<= 2 characters^[A-Z]{2}$

Example: "US"

destinationCurrencystring<= 5 characters^[A-Z]{3,5}$

The currency code of the currency in which the beneficiary will receive this payment.

Example: "USD"

destinationBlockchainNetworkstring[ 1 .. 20 ] characters

The name of the blockchain network on which the beneficiary will receive this payment.

Example: "Ethereum, TRON"

beneficiaryIdentityIdstring

The unique ID associated with the payment beneficiary's identity record.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

beneficiaryIdentityVersioninteger

The current version of the beneficiary's identity record.

Example: 1

beneficiaryIdentityNickNamestring<= 100 characters

Nickname associated with the beneficiary's identity record.

Example: "Successful business beneficiary"

payoutstring

The payout category for this payment.

Example: "BANK"

adjustedExchangeRateobject

Foreign Exchange (FX) rate used to calculate the quote.

adjustedRatenumber(double)

Value of the Foreign Exchange (FX) rate.

Example: 2

feesArray of objects

A summary of fees included in the payment quote.

totalFeenumber(double)

The value of the total fee included in this quote.

Example: 12.23

feeCurrencystring^[a-zA-Z]{3,5}$

The currency in which fees are charged.

Example: "USD"

feeBreakdownArray of objects

An array of fees that provides a breakdown of how the total fees is calculated for this quote.

calculatedFeenumber(double)

Value of the fee when the configured fee unit is applied against the value.

Example: 2.43

feeNamestring[ 1 .. 128 ] characters

The name of the fee.

Example: "Service fee"

feeDescriptionstring[ 1 .. 256 ] characters

Description of the fee.

Example: "The service fee charged for this transaction."

taxesArray of objects

A summary of taxes included in the payment quote.

totalTaxesnumber(double)

The value of the total taxes included in this quote.

Example: 5.12

taxCurrencystring^[a-zA-Z]{3,5}$

The currency in which taxes are charged.

Example: "USD"

taxBreakdownArray of objects

An array of taxes with details such as tax description, rate, name and tax amount.

taxAmountnumber(double)

tax amount for this tax line item.

Example: 2.43

taxNamestring[ 1 .. 128 ] characters

The name of the tax.

Example: "ISS/ VAT/ GST etc"

taxDescriptionstring[ 1 .. 256 ] characters

GST service fee tax .

Example: "The service fee tax charged for this transaction."

taxRatenumber(double)

The tax rate applied to calculate the tax amount.

Example: 5

sourceOfCashstring

Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.

Example: "EMIN"

purposeCodestring

Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.

Example: "PAYR"

transactionDetailsobject

A summary of the payment category.

paymentProductstring or null

The Ripple payments product used to make this payment.

Value	Description
LICENSED	Identifies a transaction using Ripple Payments Direct.

flowTypestring or null

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. Identification of third-party payment: If the `thirdPartyPayment` property is `true`, it indicates that you're making this payment on behalf of a business originator. If the `thirdPartyPayment` property is `false`, it indicates that you are the business originator making this payment.
B2C	Specifies that this payment is made by a business originator to an individual beneficiary. Identification of third-party payment: If the `thirdPartyPayment` property is `true`, it indicates that you're making this payment on behalf of a business originator. If the `thirdPartyPayment` property is `false`, it indicates that you are the business originator making this payment.

thirdPartyPaymentboolean or null

Flag to indicate if this payment is initiated on behalf of a third-party originator.

Example: false

businessUseCasestring or null

Indicates the type of payment you're making.

Value	Description
FIAT_TRANSFER	Indicates fiat source currency to fiat destination.

paymentLabelsArray of strings<= 10 items

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

receiverRelationshipstring

The relationship to the debtor.

Example: "SUBS"

paymentMemostring<= 140 characters^[A-Z0-9 ,.()/-]*$

Example: "ORDER 2025-09-001 PAYMENT"

Response

application/json

{
  "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": {
    "beneficiaryFinancialInstrumentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    "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": "string",
    "thirdPartyPayment": false,
    "businessUseCase": "string"
  },
  "paymentLabels": [
    "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
  ],
  "receiverRelationship": "SUBS",
  "paymentMemo": "ORDER 2025-09-001 PAYMENT"
}

Get a payment by ID (v3)

Request

Gets a payment by ID.

Security

Bearer

Path

paymentIdstring(uuid)required

Unique identifier of the payment to get.

Example: 7ea3399c-1234-5678-8d8f-d320ea406630

curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/payments/7ea3399c-1234-5678-8d8f-d320ea406630 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successfully fetched payment details.

Bodyapplication/json

paymentIdstring(uuid)<= 36 charactersrequired

The unique ID that identifies this payment. This value is the same as the quote ID.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

cryptoTransactionHashstring

Transaction hash of the crypto payment on the destination blockchain network

Example: "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb"

initiatedAtstring(date-time)

The time at which the payment was initiated, specified in UTC.

Example: "2019-08-24T14:15:22Z"

expiresAtstring(date-time)

The time at which this payment expires, specified in UTC.

Example: "2019-08-24T14:15:22Z"

lastStateUpdatedAtstring(date-time)

The time at which the payment state was last updated for this payment, specified in UTC.

Example: "2019-08-24T14:15:22Z"

paymentStatestringrequired

Current state of a payment.

The payment lifecycle currently uses the following values:

QUOTED
INITIATED
VALIDATING
TRANSFERRING
COMPLETED
FAILED
RETURNED
DECLINED

Additional states may be introduced in the future without breaking existing integrations.

Enum Value	Description
QUOTED	A quote has been created, but the payment has not yet been initiated.
INITIATED	The payment has been submitted and is awaiting validation.
VALIDATING	Ripple is validating the payment details and reserving funds from the originator’s available balance.
TRANSFERRING	The payment is being processed and funds are moving through the network toward the beneficiary.
COMPLETED	The payment has completed and the beneficiary has received the funds.
FAILED	The payment could not be completed. 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.
RETURNED	The payment was returned by a downstream institution. 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.
DECLINED	The payment was declined due to user input errors or business rule violations. The decline 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.

Example: "INITIATED"

originatorobject

Payment originator and source details.

originatorIdentityIdstring

The unique ID associated with the payment originator's identity record.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

originatorIdentityIdVersioninteger

The current version of the originator's identity record.

Example: 1

originatorIdentityNickNamestring<= 100 characters

Nickname associated with the originator's identity record.

Example: "Successful Business Sender"

internalIdstring<= 35 characters

An ID associated with this payment, if provided by the customer during payment initiation.

Example: "Invoice-123"

sourceCurrencystring<= 5 characters^[A-Z]{3,5}$

originator's currency

Example: "USD"

sourceAmountnumber(double)

The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.

Example: 100

payinstring

Details about how this payment is funded.

Example: "FUNDED"

destinationobject

beneficiaryFinancialInstrumentIdstring

The financial instrument ID, the identity ID of the payment beneficiary is related to.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

destinationAmountnumber(double)

The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.

Example: 1234.111223

destinationCountrystring<= 2 characters^[A-Z]{2}$

Example: "US"

destinationCurrencystring<= 5 characters^[A-Z]{3,5}$

The currency code of the currency in which the beneficiary will receive this payment.

Example: "USD"

destinationBlockchainNetworkstring[ 1 .. 20 ] characters

The name of the blockchain network on which the beneficiary will receive this payment.

Example: "Ethereum, TRON"

beneficiaryIdentityIdstring

The unique ID associated with the payment beneficiary's identity record.

Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

beneficiaryIdentityVersioninteger

The current version of the beneficiary's identity record.

Example: 1

beneficiaryIdentityNickNamestring<= 100 characters

Nickname associated with the beneficiary's identity record.

Example: "Successful business beneficiary"

payoutstring

The payout category for this payment.

Example: "BANK"

adjustedExchangeRateobject

Foreign Exchange (FX) rate used to calculate the quote.

adjustedRatenumber(double)

Value of the Foreign Exchange (FX) rate.

Example: 2

feesArray of objects

A summary of fees included in payment quote.

totalFeenumber(double)

The value of the total fee included in this quote.

Example: 12.23

feeCurrencystring^[a-zA-Z]{3,5}$

The currency in which fees are charged.

Example: "USD"

feeBreakdownArray of objects

An array of fees that provides a breakdown of how the total fees is calculated for this quote.

calculatedFeenumber(double)

Value of the fee when the configured fee unit is applied against the value.

Example: 2.43

feeNamestring[ 1 .. 128 ] characters

The name of the fee.

Example: "Service fee"

feeDescriptionstring[ 1 .. 256 ] characters

Description of the fee.

Example: "The service fee charged for this transaction."

taxesArray of objects

A summary of taxes included in the payment quote.

totalTaxesnumber(double)

The value of the total taxes included in this quote.

Example: 5.12

taxCurrencystring^[a-zA-Z]{3,5}$

The currency in which taxes are charged.

Example: "USD"

taxBreakdownArray of objects

An array of taxes with details such as tax description, rate, name and tax amount.

taxAmountnumber(double)

tax amount for this tax line item.

Example: 2.43

taxNamestring[ 1 .. 128 ] characters

The name of the tax.

Example: "ISS/ VAT/ GST etc"

taxDescriptionstring[ 1 .. 256 ] characters

GST service fee tax .

Example: "The service fee tax charged for this transaction."

taxRatenumber(double)

The tax rate applied to calculate the tax amount.

Example: 5

sourceOfCashstring

Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.

Example: "EMIN"

purposeCodestring

Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.

Example: "PAYR"

transactionDetailsobject

A summary of the payment category.

paymentProductstring or null

The Ripple payments product used to make this payment.

Value	Description
LICENSED	Identifies a transaction using Ripple Payments Direct.

flowTypestring or null

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. Identification of third-party payment: If the `thirdPartyPayment` property is `true`, it indicates that you're making this payment on behalf of a business originator. If the `thirdPartyPayment` property is `false`, it indicates that you are the business originator making this payment.
B2C	Specifies that this payment is made by a business originator to an individual beneficiary. Identification of third-party payment: If the `thirdPartyPayment` property is `true`, it indicates that you're making this payment on behalf of a business originator. If the `thirdPartyPayment` property is `false`, it indicates that you are the business originator making this payment.

thirdPartyPaymentboolean or null

Flag to indicate if this payment is initiated on behalf of a third-party originator.

Example: false

businessUseCasestring or null

Indicates the type of payment you're making.

Value	Description
FIAT_TRANSFER	Indicates fiat source currency to fiat destination.

errorsArray of objects

codestringrequired

A unique identifier for the error

Example: "SYS_003"

typestringrequired

A high-level categorization of the error, indicating the type of issue that occurred

Example: "SYSTEM_ERROR"

titlestringrequired

A brief, user-friendly description of the error

Example: "Internal Server Error"

descriptionstringrequired

A more detailed explanation of the error, potentially including information about what caused the error and the next steps

Example: "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."

timestampstring(date-time)required

Example: "2024-11-21T14:15:22Z"

paymentLabelsArray of strings<= 10 items

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

receiverRelationshipstring

The relationship to the debtor.

Example: "SUBS"

paymentMemostring<= 140 characters^[A-Z0-9 ,.()/-]*$

Example: "ORDER 2025-09-001 PAYMENT"

Response

application/json

{
  "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": {
    "beneficiaryFinancialInstrumentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    "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": "string",
    "thirdPartyPayment": false,
    "businessUseCase": "string"
  },
  "errors": [
    { … }
  ],
  "paymentLabels": [
    "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
  ],
  "receiverRelationship": "SUBS",
  "paymentMemo": "ORDER 2025-09-001 PAYMENT"
}

Get state transitions by payment ID (v3)

Request

Gets the state transitions for a payment by ID.

Security

Bearer

Path

paymentIdstring(uuid)required

Unique identifier of the payment for which you want to get state transition information.

Example: 7ea3399c-1234-5678-8d8f-d320ea406630

curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/payments/7ea3399c-1234-5678-8d8f-d320ea406630/states \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successfully fetched payment state transitions.

Bodyapplication/json

stateTransitionsArray of objectsrequired

updatedFromstringrequired

Current state of a payment.

The payment lifecycle currently uses the following values:

QUOTED
INITIATED
VALIDATING
TRANSFERRING
COMPLETED
FAILED
RETURNED
DECLINED

Additional states may be introduced in the future without breaking existing integrations.

Enum Value	Description
QUOTED	A quote has been created, but the payment has not yet been initiated.
INITIATED	The payment has been submitted and is awaiting validation.
VALIDATING	Ripple is validating the payment details and reserving funds from the originator’s available balance.
TRANSFERRING	The payment is being processed and funds are moving through the network toward the beneficiary.
COMPLETED	The payment has completed and the beneficiary has received the funds.
FAILED	The payment could not be completed. 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.
RETURNED	The payment was returned by a downstream institution. 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.
DECLINED	The payment was declined due to user input errors or business rule violations. The decline 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.

Example: "INITIATED"

updatedTostringrequired

Current state of a payment.

The payment lifecycle currently uses the following values:

QUOTED
INITIATED
VALIDATING
TRANSFERRING
COMPLETED
FAILED
RETURNED
DECLINED

Additional states may be introduced in the future without breaking existing integrations.

Enum Value	Description
QUOTED	A quote has been created, but the payment has not yet been initiated.
INITIATED	The payment has been submitted and is awaiting validation.
VALIDATING	Ripple is validating the payment details and reserving funds from the originator’s available balance.
TRANSFERRING	The payment is being processed and funds are moving through the network toward the beneficiary.
COMPLETED	The payment has completed and the beneficiary has received the funds.
FAILED	The payment could not be completed. 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.
RETURNED	The payment was returned by a downstream institution. 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.
DECLINED	The payment was declined due to user input errors or business rule violations. The decline 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.

Example: "INITIATED"

updatedAtstring(date-time)required

The timestamp when the payment state was updated.

Example: "2024-08-13T20:15:50.990995Z"

Response

application/json

{
  "stateTransitions": [
    { … }
  ]
}

Update payment labels (v3)

Request

Add or remove labels for a payment.

Security

Bearer

Path

paymentIdstring(uuid)required

The unique ID that identifies the payment for which you want to update labels.

Example: 7ea3399c-1234-5678-8d8f-d320ea406630

Bodyapplication/jsonrequired

Labels to add to or remove from the payment.

labelsToAddArray of strings<= 10 items

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

labelsToRemoveArray of strings<= 10 items

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

curl -i -X PATCH \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/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"
    ]
  }'

Responses

Successfully updated the payment labels.

Bodyapplication/json

labelsArray of strings<= 10 itemsrequired

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]

Response

application/json

{
  "labels": [
    "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
  ]
}

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.

Operations

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.

Operations

Payments Direct API (0.0.3)

API environments

API authentication

Generate client ID and client secret

Request an access token

Authentication

Identities (v3)

Identities (v2) — Legacy

Quotes

Payments (v3)

Search payments (v3)

Request

Responses

Was this page helpful?

Create payment (v3)

Request

Responses

Was this page helpful?

Get a payment by ID (v3)

Request

Responses

Was this page helpful?

Get state transitions by payment ID (v3)

Request

Responses

Was this page helpful?

Update payment labels (v3)

Request

Responses

Was this page helpful?

Payments (v2) - Legacy

Ledger

Payments Direct API (0.0.3)

API environments

API authentication

Generate client ID and client secret

Request an access token

Authentication

Identities (v3)

Identities (v2) — Legacy

Quotes

Payments (v3)

Search payments (v3)

RequestExpand all

Responses

Was this page helpful?

Create payment (v3)

Request

Responses

Was this page helpful?

Get a payment by ID (v3)

Request

Responses

Was this page helpful?

Get state transitions by payment ID (v3)

Request

Responses

Was this page helpful?

Update payment labels (v3)

Request

Responses

Was this page helpful?

Payments (v2) - Legacy

Ledger

Request