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

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

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.

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.