Corporate Card Limits

Returns the limits set on a Sber corporate card and their remaining amounts for the user's authorized session. The method only reads data from Sber: it does not create operations or change limits.

Integration scenario

Get the session_id of an authorized Sber session — see the «General» section.
Get the business_card_id of the card with the corporate cards list method.
Calculate the signature from session_id and business_card_id and send a GET request.
Use the remaining limit amounts, for example, to show the user how much can be spent from the card. 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/corporate-cards/{business_card_id}/limits

GET https://api.baas.stage.kvell.group/v1/sber/corporate-cards/{business_card_id}/limits

Request

Path parameters

Parameter	Type	Required	Description
`business_card_id`	string	Yes	Corporate card ID in UUID format. Returned in the `business_card_id` 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`.

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}{business_card_id}{secret_key})

X-Api-Key — shop ID;
session_id — the query parameter value as is;
business_card_id — the card ID from the request path in lowercase, in hyphenated format;
secret_key — the secret key from the merchant's shop settings.

The string is encoded in UTF-8. The signature is valid only for the card whose ID is included in it: calculate a separate signature for each card.

Example

curl --request GET \
  --url 'https://api.baas.stage.kvell.group/v1/sber/corporate-cards/1d192d78-7877-412a-a17b-cceaf5de1803/limits?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 business_card_id, session_id and signature.

2004004014034044225XX

Example of a 200 (OK) response

{
  "business_card_id": "1d192d78-7877-412a-a17b-cceaf5de1803",
  "cash_limits": {
    "day": {
      "max_value": "300000.00",
      "value": "300000.00",
      "rest_volume": "300000.00"
    },
    "month": {
      "max_value": "10000000.00",
      "value": "10000000.00",
      "rest_volume": "10000000.00"
    }
  },
  "transfer_limits": {
    "day": {
      "max_value": "300000.00",
      "value": "300000.00",
      "rest_volume": "300000.00"
    },
    "month": {
      "max_value": "5000000.00",
      "value": "5000000.00",
      "rest_volume": "4999667.00"
    }
  },
  "non_cash_limit": {
    "day": {
      "value": null,
      "rest_volume": null,
      "is_active": false
    }
  },
  "total_limits": {
    "month": {
      "value": null,
      "rest_volume": null,
      "is_active": false
    },
    "period": {
      "value": "1000000.00",
      "rest_volume": "400000.00",
      "is_active": true,
      "start_date": "2026-10-01T00:00:00.000Z",
      "end_date": "2026-12-31T23:59:59.000Z",
      "block_operations_after_period": false
    }
  }
}

Response parameters

Amounts are passed as strings exactly as Sber returns them, for example "300000.00".

Parameter	Type	Description
`business_card_id`	string	Corporate card ID from the request.
`cash_limits`	object	Cash withdrawal limits. The structure is described in the «Limit object» section.
`transfer_limits`	object	Transfer limits. The structure is described in the «Limit object» section.
`non_cash_limit`	object \| null	Non-cash operations limit. `null` if Sber did not return the limit.
`non_cash_limit.day`	object	Daily limit. The structure is described in the «Toggleable limit object» section.
`total_limits`	object \| null	Total limits on spending operations. `null` if Sber did not return the limits.
`total_limits.month`	object \| null	Monthly limit. The structure is described in the «Toggleable limit object» section.
`total_limits.period`	object \| null	Limit on the amount of spending operations for a period. Contains the fields of the «Toggleable limit object» and the fields from the «Limit period» section.

What the response means

Sber returned the card limits at the time of the request. The response does not reserve any amount: the remaining amount may decrease by the time of the next card operation.

What to do next

Use rest_volume of the relevant limit as the available remaining amount.
For non_cash_limit and total_limits, take a limit into account only if is_active is true.

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 limits were 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 business_card_id was taken from the cards list of the same session, and repeat the request later.
If the error persists, 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 limits were 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, business_card_id, 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 limits were 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 limits were 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": "Field required",
      "field": "session_id"
    }
  ]
}

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. Returned for code `0`.

What the response means

The request failed the format or required parameters check. The limits were not requested.

What to do next

Fix the parameter from field or message.
If session_id or business_card_id has changed, recalculate 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 limits 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.

Limit object

The cash_limits and transfer_limits objects contain the daily and monthly limits:

Parameter	Type	Description
`day`	object	Daily limit.
`month`	object	Monthly limit.

Each of them contains the fields:

Parameter	Type	Description
`max_value`	string	Maximum value the limit can be set to.
`value`	string	Set limit value.
`rest_volume`	string	Remaining limit amount.

Toggleable limit object

The non_cash_limit.day, total_limits.month and total_limits.period objects contain the fields:

Parameter	Type	Description
`value`	string \| null	Set limit value. `null` if the limit is not set.
`rest_volume`	string \| null	Remaining limit amount. `null` if the limit is not set.
`is_active`	boolean	`true` if the limit is enabled.

Limit period

The total_limits.period object additionally contains the fields:

Parameter	Type	Description
`start_date`	string	Start date and time of the period in UTC, ISO 8601.
`end_date`	string	End date and time of the period in UTC, ISO 8601.
`block_operations_after_period`	boolean	`true` if card operations are blocked after the period ends.