List payment request search filters

List all the filters available for payment request searches, including each filter’s identifier, data type and, where applicable, allowed values. Use a filter’s Id when adding structured criteria to the Query parameter in Search payment requests.

Endpoints

EnvironmentMethod and URL
StagingGET https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/search/filters
Production – UK HubGET https://api.vitesse.io/v1/payment-initiation/paymentRequests/search/filters
Production – US HubGET https://api.us.vitesse.io/v1/payment-initiation/paymentRequests/search/filters

For help choosing an environment, see Environment.

Access requirements

Configure at least one of the following access combinations:

OAuth scopeIdentity client role
payment-requestspayment-requests.viewer
payment-requestspayment-requests.manager

For more information about scopes, see Authentication. For information about the access granted by specific roles, see Identity client roles.

Send the request

This example uses the Staging environment:

curl --request GET \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/search/filters' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json'

Replace <access-token> with a valid access token that contains the required scope, and any example values with your own details.

Example response

A successful request returns 200 OK with a SearchFilters array. Each entry includes an Id, Name and Type. AllowedValues lists the permitted values where applicable; it is null when the filter does not have a fixed list.

The example shows selected filters. The endpoint also returns filters for other searchable fields, such as Recipient.Name, Recipient.Email, RecipientReference, Status and CreatedAt.

{
  "SearchFilters": [
    {
      "Id": "Id",
      "Name": "Id",
      "Type": "String",
      "AllowedValues": null,
      "AllowedKeyedValues": null
    },
    {
      "Id": "PaymentMethod",
      "Name": "PaymentMethod",
      "Type": "Enum",
      "AllowedValues": [
        "BankAccount",
        "Echeck",
        "Card",
        "PostalCheque"
      ],
      "AllowedKeyedValues": null
    },
    {
      "Id": "SendValue",
      "Name": "SendValue",
      "Type": "FractionalNumber",
      "AllowedValues": null,
      "AllowedKeyedValues": null
    },
    {
      "Id": "Recipient.Type",
      "Name": "Type",
      "Type": "Enum",
      "AllowedValues": [
        "Person",
        "Business"
      ],
      "AllowedKeyedValues": null
    },
    {
      "Id": "Recipient.Country",
      "Name": "Country",
      "Type": "String",
      "AllowedValues": [
        "GB"
      ],
      "AllowedKeyedValues": null
    }
  ]
}

The allowed values for Recipient.Country, SendCurrency and ReceiveCurrency depend on the payment requests available to the merchant. For nested fields, use the complete property path returned in Id, such as Recipient.Country.

Use the returned Id and, where provided, AllowedValues to build a structured Query. For example, use (Recipient.Country: "GB") to filter for payment requests with a recipient in Great Britain.

Troubleshoot requests

If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.

For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.

Next steps

Use the returned filter IDs and values in the Query parameter when you Search payment requests.