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

EnvironmentEndpoint
StagingGET https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/search
Production – UK HubGET https://api.vitesse.io/v1/payment-initiation/paymentRequests/search
Production – US HubGET 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 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.

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.

ParameterTypeWhen to use it
ContinuationTokenStringRetrieve the next page. Use the token returned in the previous response with the same search parameters.
FreeTextStringSearch for text, such as Thornton. You can combine this with Query to narrow the results.
PageSizeIntegerSet the maximum number of results per page. The default is 10 with a range from 1 to 100.
QueryStringApply 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​.
SortQueryStringSort 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.