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
| Environment | Method and URL |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/merchantAccounts/search |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/merchantAccounts/search |
| Production – US Hub | GET https://api.us.vitesse.io/v1/payment-initiation/merchantAccounts/search |
For help choosing an environment, see Environment.
Access requirements
Configure the following access:
| OAuth scope | Identity client role |
|---|---|
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 optional parameters to filter matching accounts and control the number returned.
| Parameter | Type | When to use it |
|---|---|---|
name | String | Filter using all or part of the account name. |
currencyCode | String | Filter accounts by the three-letter ISO 4217 currency code, for example GBP. |
limit | Integer | Set the maximum number of matching accounts to return. |
offset | Integer | Skip this number of matching accounts before returning results. |
query | String | Apply additional structured filters. |
sortQuery | String | Sort the matching accounts. |
Send the request
Use the following optional query parameters to filter the results:
| Query parameter | Description |
|---|---|
name | Filter using all or part of the account name. |
currencyCode | Filter 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.
Updated 15 days ago