Баланс
Методы для работы с балансом аккаунта: история, расчёт стоимости, пополнение.
Обзор
Модуль для работы с балансом аккаунта. Позволяет рассчитывать стоимость пополнения и пополнять баланс.
GET /profile/balance/calculate
Рассчитать стоимость пополнения баланса.
Rate Limit: 5 req/sec
Query Parameters
| Parameter | Type | Required | Validation | Description |
|---|---|---|---|---|
amount | number | Да | @IsInt @Min(1) @Max(100001) | Сумма в рублях (1-100001) |
Пример запроса
curl -X GET "https://api.stealthsurf.net/profile/balance/calculate?amount=500" \
-H "Authorization: Bearer stlth_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYY"Ответ
{
status: true,
statusCode: 200,
data: Array<{
id: number
method_key: string // sbp | ton | usdt | telegram_stars | etc.
display_name: string // Название способа оплаты
price: number // Стоимость в валюте способа оплаты
currency: string // RUB | TON | USDT | STARS | etc.
}>
}Пример ответа
{
"status": true,
"statusCode": 200,
"data": [
{
"id": 1,
"method_key": "sbp",
"display_name": "СБП",
"price": 500,
"currency": "RUB"
},
{
"id": 4,
"method_key": "ton",
"display_name": "TON",
"price": 1.42,
"currency": "TON"
},
{
"id": 7,
"method_key": "telegram_stars",
"display_name": "Telegram Stars",
"price": 320,
"currency": "STARS"
}
]
}В ответ не попадают неактивные методы, а также методы balance и promocode. Методы с суммой ниже min_amount исключаются (кроме referral). Сортировка — по полю position, затем по id.
Для ton, usdt (включая варианты usdt_*) и telegram_stars сумма конвертируется по текущему курсу. Если курс недоступен, способ оплаты не попадает в ответ.
POST /profile/balance/topup
Пополнить баланс. Создаётся запись в истории платежей и возвращается ссылка на оплату. Для способа telegram_stars возвращается deep-link Telegram-бота, для способа referral средства переводятся с реферального баланса на основной.
Rate Limit: 1 req/sec
Request Body
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
amount | number | Да | @IsInt @Min(1) @Max(100001) | Сумма в рублях (1-100001) |
payment_method_id | number | Да | @IsInt | ID способа оплаты. Способ должен быть активным и не быть balance или promocode |
Заголовки
| Header | Описание |
|---|---|
x-forwarded-for | IP-адрес клиента (сохраняется в зашифрованном виде и учитывается платёжным шлюзом) |
Пример запроса
curl -X POST "https://api.stealthsurf.net/profile/balance/topup" \
-H "Authorization: Bearer stlth_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYY" \
-H "Content-Type: application/json" \
-d '{
"amount": 500,
"payment_method_id": 1
}'Ответ
{
status: true,
statusCode: 201,
data: {
link: string // Ссылка на оплату (для telegram_stars — deep-link бота)
}
}Пример ответа
{
"status": true,
"statusCode": 201,
"data": {
"link": "https://sbp.fk.life/pay/1234567890"
}
}Ответ (перевод с реферального баланса)
При пополнении основного баланса с реферального ответ — просто true (а не объект с link). Перевод выполняется внутри транзакции.
{
status: true,
statusCode: 201,
data: true
}Ошибки
| errorCode | message | Когда |
|---|---|---|
| 3 | bad request | Способ оплаты не найден или неактивен; выбран balance или promocode; недоступен курс TON / USDT / Stars; у пользователя установлен флаг withdrawalBlocked при пополнении с реферального баланса; не удалось сгенерировать deep-link Telegram; у способа не задан payment_method_id; платёжный шлюз не вернул ссылку |
| 15 | referral balance not enough | Недостаточно средств на реферальном балансе при пополнении способом referral |
| 46 | invalid topup amount | Рассчитанная сумма меньше минимальной суммы (min_amount) выбранного способа оплаты |
Минимальная сумма пополнения — 1 рубль, максимальная — 100001 рубль. Дополнительно у каждого способа оплаты есть собственный минимум min_amount: если рассчитанная сумма меньше него, запрос вернёт ошибку 46.
GET /profile/balance/monthly-spend
Получить нормализованные ежемесячные расходы по автопродлеваемым подпискам (конфиги, облачные серверы, платные опции), списываемым с баланса.
Rate Limit: 5 req / 1 sec
Пример запроса
curl -X GET "https://api.stealthsurf.net/profile/balance/monthly-spend" \
-H "Authorization: Bearer stlth_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYY"Ответ
{
status: true,
statusCode: 200,
data: {
total: number // Суммарные расходы за месяц
currency: string // Валюта (RUB)
has_active_renewals: boolean // Есть ли активные автопродления
next_charge: { // null, если нет активных автопродлений
at: number // Unix timestamp следующего списания
amount: number // Сумма ближайшего списания
} | null
items: Array<{
type: string // config | cloud_server | paid_option
id: number // Идентификатор подписки
title: string // Название подписки
days: number // Длительность цикла продления в днях
charge_amount: number // Реальная сумма списания за один цикл
price_per_month: number // Та же сумма в пересчёте на 30 дней (для отображения)
expires_at: number // Unix timestamp окончания текущего периода
}>
}
}Пример ответа
{
"status": true,
"statusCode": 200,
"data": {
"total": 750,
"currency": "RUB",
"has_active_renewals": true,
"next_charge": {
"at": 1716153600,
"amount": 250
},
"items": [
{
"type": "config",
"id": 12,
"title": "🇳🇱 Нидерланды",
"days": 30,
"charge_amount": 250,
"price_per_month": 250,
"expires_at": 1716153600
},
{
"type": "cloud_server",
"id": 87,
"title": "🇩🇪 Германия",
"days": 90,
"charge_amount": 1500,
"price_per_month": 500,
"expires_at": 1723929600
}
]
}
}Учитываются только подписки с включённым auto_renewal, заданным auto_renewal_days и активным тарифом с оплатой через balance. Результат кэшируется на 60 секунд.
Значение total считается по неокруглённым величинам и округляется один раз, поэтому может отличаться от суммы items[].price_per_month не более чем на 1 рубль. Если активных автопродлений нет, возвращается total: 0, has_active_renewals: false, next_charge: null и пустой items.
Помогла ли вам эта статья?