Оплата и счета
Баланс, пополнение, история операций; для юрлиц — реквизиты, счета, PDF и закрывающие акты
Базовый адрес — https://api.iskragen.ru. Общие правила — в обзоре справочника.
GET /v1/billing/balance
Получить баланс. Возвращает availableRub, reservedRub и lifetimeRub, не меняя деньги; значение кэшируется на 30 секунд, а fresh=true читает без кэша. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает 429 RATE_LIMIT_ERROR с retryAfter, а отсутствие ключа — 401 AUTHENTICATION_ERROR.
Авторизация: заголовок Authorization: Bearer <ключ> — API-ключ, выданный в личном кабинете (isk_live_<prefix>_<secret>).
Параметры
| Параметр | Где | Тип | Обязательный | Описание и ограничения |
|---|---|---|---|---|
fresh | query | boolean | нет | — |
Пример вызова
curl -X GET "https://api.iskragen.ru/v1/billing/balance" \
-H "Authorization: Bearer $ISKRAGEN_API_KEY"
Структура ответа 200
Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — object.
| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
availableRub | number | да | — |
currency | string | да | значения: RUB |
lifetimeRub | number | да | — |
reservedRub | number | да | — |
Коды ошибок
401 AUTHENTICATION_ERROR— ключ отсутствует, невалиден или отозван.429 RATE_LIMIT_ERROR— превышен лимит запросов либо число одновременных генераций (по умолчанию 5).
GET /v1/billing/payments/{id}
Статус платежа. Опрос статуса возвращает итоговые флаги terminal и succeeded; статус отражает оплату у провайдера, а не обязательно зачисление на баланс. Это чтение с побочным эффектом: для CONFIRMED вызов зачисляет сумму и бонус на баланс, повтор безопасен и дважды не зачисляет, а иначе операцию завершит фоновая сверка раз в 5 минут. Для REJECTED и DEADLINE_EXPIRED пополнение не состоялось и баланс остаётся без изменений; если такая попытка позднее стала оплачена, то в первые 7 суток она зачисляется автоматически, а для оплаты неудавшейся попытки старше 7 суток зачисление на баланс произойдёт только после ручного разбора, не автоматически. Для REVERSED, REFUNDED, PARTIAL_REFUNDED баланс автоматически не пересчитывается, возврат разбирается вручную. Чужой платёж возвращает 404; доступ: Требуется API-ключ, действует общий лимит 60 запросов в минуту, превышение возвращает 429 RATE_LIMIT_ERROR с retryAfter, а отсутствие ключа — 401 AUTHENTICATION_ERROR.
Авторизация: заголовок Authorization: Bearer <ключ> — API-ключ, выданный в личном кабинете (isk_live_<prefix>_<secret>).
Параметры
| Параметр | Где | Тип | Обязательный | Описание и ограничения |
|---|---|---|---|---|
id | path | string | да | длина ≥ 1; длина ≤ 128 |
Пример вызова
curl -X GET "https://api.iskragen.ru/v1/billing/payments/<id>" \
-H "Authorization: Bearer $ISKRAGEN_API_KEY"
Структура ответа 200
Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — object.
| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
amountRub | number | да | — |
confirmedAt | string | null | да | — |
createdAt | string | да | — |
errorCode | string | null | да | — |
errorMessage | string | null | да | — |
id | string | да | — |
status | string | да | — |
succeeded | boolean | да | — |
terminal | boolean | да | — |
Коды ошибок
401 AUTHENTICATION_ERROR— ключ отсутствует, невалиден или отозван.404— Ресурс не существует или принадлежит другому пользователю429 RATE_LIMIT_ERROR— превышен лимит запросов либо число одновременных генераций (по умолчанию 5).
POST /v1/billing/topup
Создать пополнение. Создаёт платёж и возвращает paymentUrl, но оплату не проводит: человек платит на странице банка, баланс меняется после подтверждения платежа, не после ответа 200; сумма — от 100 до 100 000 ₽, successUrl и failUrl задают адреса возврата, серверные лимиты могут меняться и на момент публикации составляют 5 попыток за 10 минут и 50 000 ₽ в день с 429 DAILY_CAP_EXCEEDED. Необязательный Idempotency-Key длиной 1–64 символа действует в пределах аккаунта бессрочно, пустой или длиннее 64 символов заголовок возвращает 400; повтор проверяется до лимитов и не расходует их: без заголовка каждый вызов создаёт новый платёж, новый ключ создаёт платёж с 200, тот же ключ и та же сумма возвращают с 200 прежние paymentId и paymentUrl, другая сумма — 409 IDEMPOTENCY_KEY_REUSED, выполняющийся первый запрос — 409 IDEMPOTENCY_IN_PROGRESS с Retry-After: 5, а попытка, завершившаяся без действующей ссылки из-за ошибки, отмены, отказа или возврата, — 409 IDEMPOTENCY_KEY_BURNED, и для нового пополнения нужен новый ключ; сверяется сумма (500 и 500.00 — одна сумма), а successUrl, failUrl и description не сверяются. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает 429 RATE_LIMIT_ERROR с retryAfter, а отсутствие ключа — 401 AUTHENTICATION_ERROR.
Авторизация: заголовок Authorization: Bearer <ключ> — API-ключ, выданный в личном кабинете (isk_live_<prefix>_<secret>).
Параметры
| Параметр | Где | Тип | Обязательный | Описание и ограничения |
|---|---|---|---|---|
idempotency-key | header | string | нет | длина ≥ 1; длина ≤ 64 |
Тело запроса (application/json)
| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
amountRub | number | да | ≥ 100; ≤ 100000 |
description | string | нет | длина ≤ 255 |
failUrl | string | нет | формат uri |
successUrl | string | нет | формат uri |
Пример вызова
curl -X POST "https://api.iskragen.ru/v1/billing/topup" \
-H "Authorization: Bearer $ISKRAGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amountRub":100}'
Структура ответа 200
Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — object.
| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
paymentId | string | да | — |
paymentUrl | string | да | — |
Пример ответа
Пример ответа сервера; значения синтетические.
{
"paymentId": "01a0b3cc-02d4-7f18-a3b9-6e07c25d14f0",
"paymentUrl": "https://pay.example.com/checkout/01a0b3cc-02d4-7f18-a3b9-6e07c25d14f0"
}
Коды ошибок
400— Неверные параметры запроса (см.code)401 AUTHENTICATION_ERROR— ключ отсутствует, невалиден или отозван.409 IDEMPOTENCY_IN_PROGRESS— Конфликт состояния (например, уже выполняется идемпотентный запрос)409 IDEMPOTENCY_KEY_BURNED— Конфликт состояния (например, уже выполняется идемпотентный запрос)409 IDEMPOTENCY_KEY_REUSED— Конфликт состояния (например, уже выполняется идемпотентный запрос)429 DAILY_CAP_EXCEEDED— исчерпан суточный лимит пополнений.429 RATE_LIMIT_ERROR— превышен лимит запросов либо число одновременных генераций (по умолчанию 5).
GET /v1/billing/topup/pending
Последнее пополнение. Возвращает paymentId последней попытки пополнения за последний час, у которой уже есть платёж в банке, или null, чтобы после возврата со страницы банка опросить её статус; попытки старше часа не возвращаются. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает 429 RATE_LIMIT_ERROR с retryAfter, а отсутствие ключа — 401 AUTHENTICATION_ERROR.
Авторизация: заголовок Authorization: Bearer <ключ> — API-ключ, выданный в личном кабинете (isk_live_<prefix>_<secret>).
Пример вызова
curl -X GET "https://api.iskragen.ru/v1/billing/topup/pending" \
-H "Authorization: Bearer $ISKRAGEN_API_KEY"
Структура ответа 200
Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — object.
| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
paymentId | string | null | да | — |
Коды ошибок
401 AUTHENTICATION_ERROR— ключ отсутствует, невалиден или отозван.429 RATE_LIMIT_ERROR— превышен лимит запросов либо число одновременных генераций (по умолчанию 5).
GET /v1/billing/transactions
История операций. Возвращает только для чтения курсорный список с limit от 1 до 200, по умолчанию 50, полями cursor, nextCursor, hasMore и фильтрами type, status, dateFrom, dateTo. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает 429 RATE_LIMIT_ERROR с retryAfter, а отсутствие ключа — 401 AUTHENTICATION_ERROR.
Авторизация: заголовок Authorization: Bearer <ключ> — API-ключ, выданный в личном кабинете (isk_live_<prefix>_<secret>).
Параметры
| Параметр | Где | Тип | Обязательный | Описание и ограничения |
|---|---|---|---|---|
type | query | string | нет | — |
status | query | string | нет | — |
dateFrom | query | string | нет | — |
dateTo | query | string | нет | — |
externalRefPrefix | query | string | нет | — |
cursor | query | string | нет | — |
limit | query | integer | нет | ≥ 1; ≤ 200; по умолчанию 50 |
Пример вызова
curl -X GET "https://api.iskragen.ru/v1/billing/transactions" \
-H "Authorization: Bearer $ISKRAGEN_API_KEY"
Структура ответа 200
Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — object.
| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
hasMore | boolean | да | — |
items | object[] | да | — |
items[].amountRub | number | да | — |
items[].balanceAfterRub | number | да | — |
items[].createdAt | string | да | — |
items[].expiresAt | string | null | да | — |
items[].externalRef | string | null | да | — |
items[].id | string | да | — |
items[].status | string | да | — |
items[].type | string | да | — |
nextCursor | string | null | да | — |
Коды ошибок
401 AUTHENTICATION_ERROR— ключ отсутствует, невалиден или отозван.429 RATE_LIMIT_ERROR— превышен лимит запросов либо число одновременных генераций (по умолчанию 5).