Quickstart: list accounts

Use this quickstart to authenticate and make your first request to the Vitesse API.

You will request an access token, list merchant accounts and confirm that your application can send and receive API data.

A successful account request returns account identifiers, names, currencies, payment limits, subtypes, statuses and access information.

Before you begin

Create an identity client for the Staging environment and ensure that it has the following access:

RequirementValueMore information
Required OAuth scopepayment-requestsSee Authentication.
Required identity client rolepayment-requests.managerIn the UI, this role appears as Payment Requests Manager. See Identity client roles.

For instructions on creating an identity client, see Manage identity clients.

Request an access token

Request a short-lived access token for the Staging environment. Send the identity client credentials as form data and request the payment-requests scope.

Endpoint: POST https://staging-identity.vitessepsp.com/connect/token

curl --request POST \
  --url 'https://staging-identity.vitessepsp.com/connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=<client-id>' \
  --data-urlencode 'client_secret=<client-secret>' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=payment-requests'

Replace <client-id> and <client-secret> with the Staging identity client credentials.

Understand the response

A successful request returns 200 OK and a short-lived bearer access token, for example:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "payment-requests"
}

The value of expires_in represents the number of seconds until the access token expires.

Use the access_token value to authenticate subsequent API requests. Store it securely and do not expose it in client-side code or logs.

📘

If your application needs continued access, request a new access token before the current token expires.

List the accounts

Request a list of merchant accounts. Include the access token from step 1 in the Authorization header.

Endpoint: GET https://api.staging.vitesse.io/v1/payment-initiation/merchantAccounts

curl --request GET \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/merchantAccounts' \
  --header 'Authorization: Bearer eyJhbGciOi...' \
  --header 'Accept: application/json'

Understand the response

A successful request returns 200 OK. The Data array contains the merchant account records returned by the operation.

This 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"
    }
  ]
}

A successful response containing one or more accounts confirms that your application can authenticate and retrieve data from this endpoint.

Troubleshoot requests

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

RequestStatusCauseAction
Access token400 Bad RequestThe request contains an invalid parameter, scope or grant type.Check the form parameters and confirm that grant_type is client_credentials.
Access token401 UnauthorizedThe identity client ID or secret is invalid.Check that you used the complete credentials for the Staging identity client.
Account retrieval401 UnauthorizedThe access token is missing, invalid or expired.Request a new access token and include it using the Bearer authentication scheme.
Account retrieval403 ForbiddenThe identity client does not have the required access.Check that the identity client has the payment-requests.manager role and that the token includes the payment-requests scope.

If Vitesse returns 200 OK with an empty Data array and you expected accounts, contact Support.

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

Next steps

A successful response confirms that your application can authenticate and retrieve account data from this endpoint.

To choose your next API task, see Welcome to the Vitesse API.