Search accounts by name or currency

Find accounts using a full or partial account name, a currency, or both. Use this search to narrow the accounts shown for selection in your application or obtain an account’s AccountId, which you can use for subsequent requests.

Search results contain summary information about each matching account. Use Retrieve an account to return more details about an account.

Endpoints

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

For help choosing an environment, see Environment.

Access requirements

Configure the following access:

OAuth scopeIdentity client role
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 optional parameters to filter matching accounts and control the number returned.

ParameterTypeWhen to use it
nameStringFilter using all or part of the account name.
currencyCodeStringFilter accounts by the three-letter ISO 4217 currency code, for example GBP.
limitIntegerSet the maximum number of matching accounts to return.
offsetIntegerSkip this number of matching accounts before returning results.
queryStringApply additional structured filters.
sortQueryStringSort the matching accounts.

Send the request

Use the following optional query parameters to filter the results:

Query parameterDescription
nameFilter using all or part of the account name.
currencyCodeFilter using the complete three-letter ISO 4217 currency code, for example GBP.

This example uses the Staging environment and searches for GBP accounts with Claims in their name, limiting the returned records to the first 10 results:

curl --get \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/merchantAccounts/search' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json' \
  --data-urlencode 'name=Claims' \
  --data-urlencode 'currencyCode=GBP' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'offset=0'

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 and a Data array containing the accounts that match the supplied search criteria.

This example returns two accounts:

{
  "Data": [
    {
      "AccountId": 4152,
      "Name": "UK Claims Account",
      "Alias": "UK claims",
      "Currency": "GBP",
      "UpperPaymentLimit": 500000.00,
      "UpperPaymentLimitCurrency": "GBP",
      "SubAccountType": "Standard"
    },
    {
      "AccountId": 4827,
      "Name": "Motor Claims Account",
      "Alias": "Motor claims",
      "Currency": "GBP",
      "UpperPaymentLimit": 250000.00,
      "UpperPaymentLimitCurrency": "GBP",
      "SubAccountType": "Payment"
    }
  ]
}

Each item contains summary information about an account. Use AccountId to retrieve the complete account information or call another operation that requires an account identifier.

Troubleshoot the request

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

If Vitesse API returns 200 OK with an empty Data array, no accounts matched the supplied search criteria. Check the account name and currency code, or remove one of the filters to broaden the search.

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

Next steps

Use the returned AccountId to:

  • Retrieve detailed information about an account.
  • Call another operation that requires an account identifier, such as making a payment.

You can also use the returned AccountId when adding an account to a programme. See Create a programme or Update a programme.