Search payment requests
Search payment requests by free text, structured filters, or both. Use this endpoint to find matching payment requests without retrieving every page of the full list.
Endpoints
| Environment | Endpoint |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/search |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/paymentRequests/search |
| Production – US Hub | GET https://api.us.vitesse.io/v1/payment-initiation/paymentRequests/search |
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.
Search parameters
Use these query parameters to search by text, apply structured filters, sort results and page through matches. You can use FreeText and Query separately or together.
| Parameter | Type | When to use it |
|---|---|---|
ContinuationToken | String | Retrieve the next page. Use the token returned in the previous response with the same search parameters. |
FreeText | String | Search for text, such as Thornton. You can combine this with Query to narrow the results. |
PageSize | Integer | Set the maximum number of results per page. The default is 10 with a range from 1 to 100. |
Query | String | Apply structured filters, such as (Recipient.Country: "GB") or (Address.City: "London"). You can combine this with FreeText to narrow the results.For more information, see Retrieve stored recipient search filters. |
SortQuery | String | Sort by a supported field and direction, such as CreatedAt desc, which will sort by CreatedAt in descending order. If you omit the direction, it defaults to asc (ascending). |
For example, to filter payment requests to recipients in Great Britain, use this Query value: (Recipient.Country: "GB").
Send the request
This example uses the Staging environment. It searches for recipients matching Thornton in London, sorts by Country descending, and returns up to 10 results:
curl --get \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/search' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--data-urlencode 'FreeText=Thornton' \
--data-urlencode 'Query=(Recipient.Country: "GB")' \
--data-urlencode 'SortQuery=CreatedAt desc' \
--data-urlencode 'PageSize=10'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 matching payment requests in the Data array and pagination details. This example returns one matching response:
{
"Data": [
{
"PaymentRequestId": "550e8400-e29b-41d4-a716-446655440000",
"SendAccountId": 3761,
"PaymentMethod": "PostalCheque",
"SendValue": 183.47,
"SendCurrency": "GBP",
"ReceiveValue": 183.47,
"ReceiveCurrency": "GBP",
"UseFxRateGroup": false,
"Recipient": {
"Type": "Person",
"Name": "Emma Thornton",
"Email": "[email protected]",
"PhoneNumber": "+442079460123",
"Country": "GB",
"Address": {
"StreetName": "High Street",
"BuildingNumber": "10",
"PostalCode": "SW1A 1AA",
"City": "London",
"CountrySubDivision": "Greater London",
"Country": "GB",
"AddressLines": [
"Flat 2"
]
}
},
"StoredRecipient": null,
"VendorRecipient": null,
"PaymentDescription": "Motor claim settlement",
"RecipientReference": "CLM-5838386",
"ExternalReference1": "CLM-5838386",
"TransactionId": null,
"Status": "Created",
"CreatedAt": "2026-10-26T09:15:00Z"
}
],
"HasMore": false,
"ContinuationToken": null,
"TotalCount": 1
}TotalCount is nullable and may be null. Use HasMore and ContinuationToken to determine whether another page is available.
Troubleshoot requests
If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.
Check that PageSize is between 1 and 100, and that the Query and SortQuery values use supported fields and syntax.
For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.
Next steps
Use Retrieve a payment request with a returned PaymentRequestId to view an individual request. Use List payment requests to retrieve requests without search criteria.
Updated 18 days ago