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
| Environment | Method and URL |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/search/filters |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/paymentRequests/search/filters |
| Production – US Hub | GET 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 scope | Identity client role |
|---|---|
payment-requests | payment-requests.viewer |
payment-requests | payment-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.
Updated 2 days ago