# Оплата и счета

Баланс, пополнение, история операций; для юрлиц — реквизиты, счета, PDF и закрывающие акты

Базовый адрес — `https://api.iskragen.ru`. Общие правила — в [обзоре справочника](/docs/api-reference).

## 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` | нет | — |

### Пример вызова

```bash
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 |

### Пример вызова

```bash
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 |

### Пример вызова

```bash
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` | да | — |

### Коды ошибок

- `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>`).

### Пример вызова

```bash
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` |

### Пример вызова

```bash
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).