# Search payments (v3)

Search for payments based on filtering criteria.

Endpoint: POST /v3/payments/filter
Version: 2026.03
Security: Bearer

## Request fields (application/json):

  - `filter` (object)
    Filter criteria to return desired payment search results.

  - `filter.paymentIds` (array)
    Specify a list of uuids to search for payment with payment ids equals one from the list
    Example: ["aaaaaaaa-1111-bbbb-abab-123412341234"]

  - `filter.paymentStates` (array)
    Array of payment states like EXECUTING or COMPLETED.
    Example: ["INITIATED"]

  - `filter.filterRangeType` (string)
    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.
    Example: "PAYMENT_CREATION"

  - `filter.beforeTimestamp` (string)
    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"

  - `filter.afterTimestamp` (string)
    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"

  - `filter.beneficiaryIdentityIds` (array)
    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"]

  - `filter.internalId` (string)
    Client-provided unique identifier for this identity. Required for Originators, optional for Beneficiaries.
    Example: "customer-12345-uuid"

  - `filter.beneficiaryIdentityNickname` (string)
    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"

  - `filter.destinationCurrencies` (array)
    Specify one or more currency codes to get payments where the beneficiary received funds in these currencies.

  - `filter.paymentLabels` (array)
    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"]

  - `sort` (object)
    Defines the sorting parameters for listing payments, including the field and sort direction.

  - `sort.sortField` (string)
    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.
    Example: "initiatedAt"

  - `sort.sortDirection` (string)
    Indicates whether results are sorted in ascending (ASC) or descending (DESC) order.
    Enum: "ASC", "DESC"

  - `page` (object)
    Specify page size and the ID of the last fetched result.

  - `page.size` (integer)
    Size of the page
    Example: 20

  - `page.lastPageToken` (string)
    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.

## Response 200 fields (application/json):

  - `data` (array)
    Array of Payment objects

  - `data.paymentId` (string, required)
    The unique ID that identifies this payment. This value is the same as the quote ID.
    Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

  - `data.cryptoTransactionHash` (string)
    Transaction hash of the crypto payment on the destination blockchain network
    Example: "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb"

  - `data.initiatedAt` (string)
    The time at which the payment was initiated, specified in UTC.
    Example: "2019-08-24T14:15:22Z"

  - `data.expiresAt` (string)
    The time at which this payment expires, specified in UTC.
    Example: "2019-08-24T14:15:22Z"

  - `data.lastStateUpdatedAt` (string)
    The time at which the payment state was last updated for this payment, specified in UTC.
    Example: "2019-08-24T14:15:22Z"

  - `data.paymentState` (string, required)
    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.
    Example: "INITIATED"

  - `data.originator` (object)
    Payment originator and source details.

  - `data.originator.originatorIdentityId` (string)
    The unique ID associated with the payment originator's identity record.
    Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

  - `data.originator.originatorIdentityIdVersion` (integer)
    The current version of the originator's identity record.
    Example: 1

  - `data.originator.originatorIdentityNickName` (string)
    Nickname associated with the originator's identity record.
    Example: "Successful Business Sender"

  - `data.originator.internalId` (string)
    Client-provided unique identifier for this identity. Required for Originators, optional for Beneficiaries.
    Example: "customer-12345-uuid"

  - `data.originator.sourceCurrency` (string)
    originator's currency
    Example: "USD"

  - `data.originator.sourceAmount` (number)
    The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.
    Example: 100

  - `data.originator.payin` (string)
    Details about how this payment is funded.
    Example: "FUNDED"

  - `data.destination` (object)

  - `data.destination.beneficiaryFinancialInstrumentId` (string)
    The financial instrument ID, the identity ID of the payment beneficiary is related to.
    Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

  - `data.destination.destinationAmount` (number)
    The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.
    Example: 1234.111223

  - `data.destination.destinationCountry` (string)
    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"

  - `data.destination.destinationCurrency` (string)
    The currency code of the currency in which the beneficiary will receive this payment.
    Example: "USD"

  - `data.destination.destinationBlockchainNetwork` (string)
    The name of the blockchain network on which the beneficiary will receive this payment.
    Example: "Ethereum, TRON"

  - `data.destination.beneficiaryIdentityId` (string)
    The unique ID associated with the payment beneficiary's identity record.
    Example: "7ea3399c-1234-5678-8d8f-d320ea406630"

  - `data.destination.beneficiaryIdentityVersion` (integer)
    The current version of the beneficiary's identity record.
    Example: 1

  - `data.destination.beneficiaryIdentityNickName` (string)
    Nickname associated with the beneficiary's identity record.
    Example: "Successful business beneficiary"

  - `data.destination.payout` (string)
    The payout category for this payment.
    Example: "BANK"

  - `data.adjustedExchangeRate` (object)
    Foreign Exchange (FX) rate used to calculate the quote.

  - `data.adjustedExchangeRate.adjustedRate` (number)
    Value of the Foreign Exchange (FX) rate.
    Example: 2

  - `data.fees` (array)
    A summary of fees included in the payment quote.

  - `data.fees.totalFee` (number)
    The value of the total fee included in this quote.
    Example: 12.23

  - `data.fees.feeCurrency` (string)
    The currency in which fees are charged.
    Example: "USD"

  - `data.fees.feeBreakdown` (array)
    An array of fees that provides a breakdown of how the total fees is calculated for this quote.

  - `data.fees.feeBreakdown.calculatedFee` (number)
    Value of the fee when the configured fee unit is applied against the value.
    Example: 2.43

  - `data.fees.feeBreakdown.feeName` (string)
    The name of the fee.
    Example: "Service fee"

  - `data.fees.feeBreakdown.feeDescription` (string)
    Description of the fee.
    Example: "The service fee charged for this transaction."

  - `data.taxes` (array)
    A summary of taxes included in the payment quote.

  - `data.taxes.totalTaxes` (number)
    The value of the total taxes included in this quote.
    Example: 5.12

  - `data.taxes.taxCurrency` (string)
    The currency in which taxes are charged.
    Example: "USD"

  - `data.taxes.taxBreakdown` (array)
    An array of taxes with details such as tax description, rate, name and tax amount.

  - `data.taxes.taxBreakdown.taxAmount` (number)
    tax amount for this tax line item.
    Example: 2.43

  - `data.taxes.taxBreakdown.taxName` (string)
    The name of the tax.
    Example: "ISS/ VAT/ GST etc"

  - `data.taxes.taxBreakdown.taxDescription` (string)
    GST service fee tax .
    Example: "The service fee tax charged for this transaction."

  - `data.taxes.taxBreakdown.taxRate` (number)
    The tax rate applied to calculate the tax amount.
    Example: 5

  - `data.sourceOfCash` (string)
    Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.
    Example: "EMIN"

  - `data.purposeCode` (string)
    Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.
    Example: "PAYR"

  - `data.transactionDetails` (object)
    A summary of the payment category.

  - `data.transactionDetails.paymentProduct` (string,null)
    The Ripple payments product used to make this payment.

  - `data.transactionDetails.flowType` (string,null)
    Specifies the type of payment you're making as categorized by the identity type of the payment originator and beneficiary.

  - `data.transactionDetails.thirdPartyPayment` (boolean,null)
    Flag to indicate if this payment is initiated on behalf of a third-party originator.

  - `data.transactionDetails.businessUseCase` (string,null)
    Indicates the type of payment you're making.

  - `data.paymentLabels` (array)
    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"]

  - `data.receiverRelationship` (string)
    The relationship to the debtor.
    Example: "SUBS"

  - `data.paymentMemo` (string)
    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"

  - `filter` (object)
    Filter criteria to return desired payment search results.

  - `filter.paymentIds` (array)
    Specify a list of uuids to search for payment with payment ids equals one from the list
    Example: ["aaaaaaaa-1111-bbbb-abab-123412341234"]

  - `filter.paymentStates` (array)
    Array of payment states like EXECUTING or COMPLETED.
    Example: ["INITIATED"]

  - `filter.filterRangeType` (string)
    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.
    Example: "PAYMENT_CREATION"

  - `filter.beforeTimestamp` (string)
    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"

  - `filter.afterTimestamp` (string)
    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"

  - `filter.beneficiaryIdentityIds` (array)
    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"]

  - `filter.beneficiaryIdentityNickname` (string)
    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"

  - `filter.destinationCurrencies` (array)
    Specify one or more currency codes to get payments where the beneficiary received funds in these currencies.

  - `sort` (object)
    Defines the sorting parameters for listing payments, including the field and sort direction.

  - `sort.sortField` (string)
    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.
    Example: "initiatedAt"

  - `sort.sortDirection` (string)
    Indicates whether results are sorted in ascending (ASC) or descending (DESC) order.
    Enum: "ASC", "DESC"

  - `page` (object)
    Specify page size and the ID of the last fetched result.

  - `page.size` (integer)
    Size of the page
    Example: 20

  - `page.lastPageToken` (string)
    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.

## Response 400 fields (application/json):

  - `errors` (object, required)

  - `errors.code` (string, required)
    A unique identifier for  the error
    Example: "SYS_003"

  - `errors.type` (string, required)
    A high-level categorization of the error, indicating the type of issue that occurred
    Example: "SYSTEM_ERROR"

  - `errors.title` (string, required)
    A brief, user-friendly description of the error
    Example: "Internal Server Error"

  - `errors.description` (string, required)
    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."

  - `errors.timestamp` (string, required)
    Example: "2024-11-21T14:15:22Z"

  - `status` (string, required)
    Error Response Status
    Example: 400

## Response 500 fields (application/json):

  - `errors` (object, required)

  - `errors.code` (string, required)
    A unique identifier for  the error
    Example: "SYS_003"

  - `errors.type` (string, required)
    A high-level categorization of the error, indicating the type of issue that occurred
    Example: "SYSTEM_ERROR"

  - `errors.title` (string, required)
    A brief, user-friendly description of the error
    Example: "Internal Server Error"

  - `errors.description` (string, required)
    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."

  - `errors.timestamp` (string, required)
    Example: "2024-11-21T14:15:22Z"

  - `status` (string, required)
    Error Response Status
    Example: 400