List accounts
List accounts and retrieve information about each account, including its currency, payment limit, account type and status.
To restrict the list by name or currency, use Search accounts by name or currency.
Endpoints
| Environment | Method and URL |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/merchantAccounts |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/merchantAccounts |
| Production – US Hub | GET https://api.us.vitesse.io/v1/payment-initiation/merchantAccounts |
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.
Send the request
This example uses the Staging environment:
curl --request GET \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/merchantAccounts' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json'Replace <access-token> with an access token that contains the required scope.
Example response
A successful request returns 200 OK and a Data array containing the accounts available to the identity client.
This abridged example returns two active accounts:
{
"Data": [
{
"MerchantId": "7d978f47-1907-4d5d-8f85-8f40a96d21c8",
"AccountId": 3761,
"Name": "UK Claims Payments",
"Alias": "UK claims",
"Currency": "GBP",
"UpperPaymentLimit": 50000.00,
"UpperPaymentLimitCurrency": "GBP",
"SubAccountType": "Standard",
"Status": "Active",
"SecurityGroupId": 142,
"LinkedMerchantIds": [
"3c84ebad-74e6-4cab-bd4f-69ba16b0308c"
],
"AccessAllowedForUserIds": [],
"UpdatedAt": "2026-09-14T10:50:36.541Z"
},
{
"MerchantId": "7d978f47-1907-4d5d-8f85-8f40a96d21c8",
"AccountId": 4827,
"Name": "US Claims Payments",
"Alias": "US claims",
"Currency": "USD",
"UpperPaymentLimit": 25000.00,
"UpperPaymentLimitCurrency": "USD",
"SubAccountType": "Payment",
"Status": "Active",
"SecurityGroupId": 142,
"LinkedMerchantIds": [
"3c84ebad-74e6-4cab-bd4f-69ba16b0308c"
],
"AccessAllowedForUserIds": [],
"UpdatedAt": "2026-09-14T10:52:18.204Z"
}
]
}Use the returned AccountId in subsequent account and payment operations.
SubAccountType identifies how the account holds or uses funds. For more information about Standard, Funding and Payment accounts, see Account types.
The account balance can change after you retrieve it. Listing accounts does not reserve funds or guarantee that the same balance will remain available for a later operation.
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.
Handle an empty result
If Vitesse returns 200 OK with an empty Data array, check which accounts the identity client can access.
Contact Support if you expected Vitesse to return accounts.
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 17 days ago