Retrieve an account balance
Retrieve an account’s current balance when you know its AccountId and do not need its full details. The response includes the currency, balance and date and time of the last update.
To retrieve the balance and detailed account information, see Retrieve an account.
Endpoints
| Environment | Method and URL |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/merchantAccounts/{id}/balance |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/merchantAccounts/{id}/balance |
| Production – US Hub | GET https://api.us.vitesse.io/v1/payment-initiation/merchantAccounts/{id}/balance |
Replace {id} with the account’s AccountId.
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 and retrieves the balance for account 4111:
curl --request GET \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/merchantAccounts/4111/balance' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json'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 the account’s balance information.
{
"MerchantId": "8e94f56b-6d5c-4fb7-b735-fef32ce8709e",
"AccountId": 4111,
"Currency": "GBP",
"Balance": 248139.87,
"UpdatedAt": "2026-09-14T14:11:04.351Z"
}This endpoint returns the balance in
Balance. Account detail responses useAccountBalance.
Checking the balance does not reserve funds. The balance can change before your application makes a payment or moves funds.
Troubleshoot the request
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.
Next steps
To review account activity, see List account entries. To view a specific balance summary, see Retrieve an account balance.
Updated 15 days ago