Account Balance

Returns the summary statement for a Sber account for a day: opening and closing balance, turnover and number of operations. The method works within the user's authorized session and only reads data from Sber: it does not create operations.

A Sber corporate card has no separate balance: the amount available on the card equals the balance of the account the card is issued to. The closing balance for the current day is the current account balance.

Integration scenario

Get the session_id of an authorized Sber session — see the «General» section.
Get the card account number in the account_number field of the corporate cards list method.
Calculate the signature from session_id and account_number and send a GET request. To get the current balance, do not pass date.
Use closing_balance as the account balance. The data is current at the time of the request: request it again when needed.

URL

ProductionStage

GET https://api.baas.kvell.group/v1/sber/accounts/{account_number}/balance

GET https://api.baas.stage.kvell.group/v1/sber/accounts/{account_number}/balance

Request

Path parameters

Parameter	Type	Required	Description
`account_number`	string	Yes	Account number — exactly 20 digits. Returned in the `account_number` field of the corporate cards list method.

Query parameters

Parameter	Type	Required	Description
`session_id`	string	Yes	ID of an authorized Sber session in UUID format. The session must belong to the Sber profile of the shop whose key is passed in `X-Api-Key`.
`date`	string	No	Statement date in `YYYY-MM-DD` format. Defaults to the current date in Moscow time. A future date is not allowed. Sber returns statements for the current and the five previous years.

Headers

Name	Type	Required	Description
`X-Api-Key`	string	Yes	Shop ID in UUID format.
`X-Signature`	string	Yes	Request signature.

Signature

The signature is a lowercase hexadecimal SHA-256 of the string built without separators in this order:

sha256({X-Api-Key}{session_id}{account_number}{secret_key})

X-Api-Key — shop ID;
session_id — the query parameter value as is;
account_number — the account number from the request path as is;
secret_key — the secret key from the merchant's shop settings.

The string is encoded in UTF-8. date is not part of the signature. The signature is valid only for the account whose number is included in it: calculate a separate signature for each account.

Example

curl --request GET \
  --url 'https://api.baas.stage.kvell.group/v1/sber/accounts/40702810600000200000/balance?session_id=11111111-1111-4111-8111-111111111111' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Signature: <signature>'

Response

Select an HTTP code to see an example, the response parameters and the recommended actions.

If no HTTP response is received

The method only reads data, so after a timeout or a dropped connection it is safe to repeat the same request with the same parameters and signature.

2004004014034044225XX

Example of a 200 (OK) response

{
  "opening_balance": {
    "amount": "301000.50",
    "currency_name": "RUB"
  },
  "opening_balance_rub": {
    "amount": "301000.50",
    "currency_name": "RUB"
  },
  "closing_balance": {
    "amount": "300000.00",
    "currency_name": "RUB"
  },
  "closing_balance_rub": {
    "amount": "300000.00",
    "currency_name": "RUB"
  },
  "debit_turnover": {
    "amount": "1500.50",
    "currency_name": "RUB"
  },
  "debit_turnover_rub": {
    "amount": "1500.50",
    "currency_name": "RUB"
  },
  "credit_turnover": {
    "amount": "500.00",
    "currency_name": "RUB"
  },
  "credit_turnover_rub": {
    "amount": "500.00",
    "currency_name": "RUB"
  },
  "debit_transactions_number": 2,
  "credit_transactions_number": 1,
  "composed_date_time": "2026-10-28T12:30:00",
  "last_movement_date": "2026-10-28",
  "prev_operation_date": "2026-10-27",
  "opening_rate": "1"
}

Response parameters

Any field can be null if Sber did not return it.

Parameter	Type	Description
`opening_balance`	object \| null	Opening balance at the start of the day in the account currency. The structure is described in the «Amount object» section.
`opening_balance_rub`	object \| null	Opening balance in roubles.
`closing_balance`	object \| null	Closing balance in the account currency. For the current day — the current account balance.
`closing_balance_rub`	object \| null	Closing balance in roubles.
`debit_turnover`	object \| null	Total debits for the day in the account currency.
`debit_turnover_rub`	object \| null	Total debits for the day in roubles.
`credit_turnover`	object \| null	Total credits for the day in the account currency.
`credit_turnover_rub`	object \| null	Total credits for the day in roubles.
`debit_transactions_number`	integer \| null	Number of debits for the day.
`credit_transactions_number`	integer \| null	Number of credits for the day.
`composed_date_time`	string \| null	Date and time the summary was composed, in Sber format, for example `2026-10-28T12:30:00`.
`last_movement_date`	string \| null	Date of the last account operation in the requested period, `YYYY-MM-DD`.
`prev_operation_date`	string \| null	Date of the previous account operation in the requested period, `YYYY-MM-DD`.
`opening_rate`	string \| null	Central Bank rate per unit of the account currency at the start of the period.

What the response means

Sber returned the account summary for the requested date. The response does not reserve any amount: the balance may change by the time of the next operation.

What to do next

Use closing_balance as the balance of the account and of all cards issued to it.
To refresh the data, repeat the request.

Example of a 400 (Bad Request) response

{
  "errors": [
    {
      "code": 4,
      "message": "Ошибка получения баланса счета. Попробуйте позднее."
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and recommendations are given in the «BAAS API errors» section.
`errors[].code`	integer	Error code. In the example — `4`, a dependent service error.
`errors[].message`	string	Error description.

What the response means

The balance was not received. Possible causes by message:

Ошибка получения баланса счета. Попробуйте позднее. — Sber rejected the request or returned an error;
Ошибка получения сессии: сессия не авторизована, требуется повторная авторизация — the user has not completed Sber authorization or the session is no longer valid;
another message starting with Ошибка получения сессии: — the session token could not be refreshed.

What to do next

If the session is not authorized or the token could not be refreshed, ask the user to go through Sber authorization again and repeat the request with the new session_id. Recalculate the signature.
Otherwise, check that account_number was taken from the cards list of the same session, and that date is not in the future and not older than the five previous years. Repeat the request later.
If the error persists for an account from the cards list, ask the user to go through Sber authorization again: during sign-in the user must grant the platform access to this account. If that does not help, contact support.

Example of a 401 (Unauthorized) response

{
  "errors": [
    {
      "code": 4,
      "message": "Ошибка получения баланса счета: сессия не авторизована"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and recommendations are given in the «BAAS API errors» section.
`errors[].code`	integer	Error code: `4` — Sber did not accept the session authorization, `11` — invalid signature.
`errors[].message`	string	Error description.

What the response means

With code 4, Sber rejected the session token and the balance was not received. With code 11, the request was rejected before calling Sber: the signature did not match.

What to do next

With code 4, ask the user to go through Sber authorization again and repeat the request with the new session_id. Recalculate the signature.
With code 11, check X-Api-Key, session_id, account_number, secret_key and the order of values in the signature. Do not repeat the request without fixing the signature.

Example of a 403 (Forbidden) response

{
  "errors": [
    {
      "code": 42,
      "message": "Доступ запрещён"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and recommendations are given in the «BAAS API errors» section.
`errors[].code`	integer	Error code: `42` — the session belongs to another Sber profile, `12` — the shop is not allowed to access the BAAS API.
`errors[].message`	string	Description of the access denial.

What the response means

The request was rejected before calling Sber, the balance was not requested.

What to do next

With code 42, check that session_id was obtained for this shop and do not use sessions of another shop.
With code 12, contact your KVELL manager to check the shop status.

Example of a 404 (Not Found) response

{
  "errors": [
    {
      "code": 4,
      "message": "Сессия не найдена"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and recommendations are given in the «BAAS API errors» section.
`errors[].code`	integer	Error code: `4` — session not found, `20` — shop not found, `43` — no Sber profile is configured for the shop.
`errors[].message`	string	Description of the resource that was not found.

What the response means

The session, shop or Sber profile was not found. The balance was not requested.

What to do next

With code 4, check session_id. If the session was not created or has been lost, ask the user to go through Sber authorization again. Repeating the request with the same session_id will not help.
With code 20, check X-Api-Key and the environment: Production or Stage.
With code 43, contact your KVELL manager to configure the Sber profile.

Example of a 422 (Unprocessable Entity) response

{
  "errors": [
    {
      "code": 0,
      "message": "String should match pattern '^[0-9]{20}$'",
      "field": "account_number"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of validation errors. Codes and recommendations are given in the «Validation errors» section.
`errors[].code`	integer	Error code. For a field error — `0`. For a `session_id` not in UUID format — `4`.
`errors[].message`	string	Reason for the validation error.
`errors[].field`	string	Parameter with an invalid value: `account_number`, `date` or `session_id`. Returned for code `0`.

What the response means

The request failed the format or required parameters check. The balance was not requested.

What to do next

Fix the parameter from field or message: the account number must be 20 digits, the date must be in YYYY-MM-DD format.
If session_id or account_number has changed, recalculate the signature. Changing date does not affect the signature.

Example of a 500 (Internal Server Error) response

{
  "errors": [
    {
      "code": 1,
      "message": "Неизвестная ошибка"
    }
  ]
}

Response parameters

Parameter	Type	Description
`errors`	array	List of errors. Codes and recommendations are given in the «Technical errors and no response» section.
`errors[].code`	integer	Technical error code: `1` or `4`.
`errors[].message`	string	Description of the technical error.

What the response means

A technical error on the KVELL side. The method only reads data, so the error does not change the balance and does not create operations.

What to do next

It is safe to repeat the same request with the same parameters and signature.
If the error persists, contact support and provide the URL, request time, X-Request-ID, HTTP code, code and message.

Amount object

All amounts in the response are passed as an object:

Parameter	Type	Description
`amount`	string	Amount as a decimal number, for example `"300000.00"`.
`currency_name`	string	Currency code, for example `RUB`.