Платежи

Пополнить баланс, посмотреть платежи, списать с сохранённой карты и настроить автопополнение через API.

Адрес

Авторизация

Ключ управления с правами billing:read, billing:write

Сам баланс отдаёт GET /aitunnel/balance, всё, что его меняло, — история баланса. Оплата от организации — в счетах и организациях. Способы оплаты, бонусы и возврат описаны в статье Баланс и оплата.

Методы

Метод	Право	Что делает
`GET /payments/methods`	`billing:read`	Способы пополнения, доступные сейчас, с минимумом и максимумом
`POST /payments`	`billing:write`	Начать пополнение. В ответе — адрес страницы оплаты
`GET /payments`	`billing:read`	Платежи аккаунта, новые первыми
`GET /payments/{id}`	`billing:read`	Один платёж: оплачен ли он
`GET /payments/cards`	`billing:read`	Сохранённые карты
`POST /payments/cards`	`billing:write`	Начать привязку карты. В ответе — адрес страницы банка
`DELETE /payments/cards/{card_id}`	`billing:write`	Удалить сохранённую карту
`POST /payments/charge`	`billing:write`	Пополнить с сохранённой карты, сразу
`GET /payments/auto-recharge`	`billing:read`	Настройки автопополнения
`PUT /payments/auto-recharge`	`billing:write`	Включить автопополнение или изменить его
`DELETE /payments/auto-recharge`	`billing:write`	Выключить автопополнение

Что открывают права

Право	Смысл
`billing:read`	Только смотреть: баланс, платежи и их статус, способы оплаты, сохранённые карты (маска номера), настройки автопополнения
`billing:write`	Тратить деньги владельца: открыть платёж, списать с сохранённой карты любую сумму в пределах лимитов, включить автопополнение, привязать и удалить карту. Включает `billing:read`

Способы оплаты

curl https://api.aitunnel.ru/v1/aitunnel/payments/methods \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

JSON

{
  "data": [
    {
      "method": "card",
      "provider": "tbank",
      "min_amount": 500,
      "max_amount": 1000000
    },
    {
      "method": "crypto",
      "provider": "nowpayments",
      "min_amount": 1500,
      "max_amount": 1000000
    },
    {
      "method": "company_sbp",
      "provider": "tbank_b2b_sbp",
      "min_amount": 10000,
      "max_amount": 100000000
    },
    {
      "method": "invoice",
      "provider": "tbank_invoice",
      "min_amount": 10000,
      "max_amount": 100000000
    }
  ]
}

В списке только то, чем можно оплатить сейчас. min_amount и max_amount — пределы суммы в целых рублях, оба включительно.

method	Смысл
`card`	Страница банка: карта, СБП, T-Pay. Есть всегда
`crypto`	Криптовалюта через NOWPayments
`foreign_card`	Иностранная карта
`company_sbp`	СБП от имени организации; нужен `company_id` из сохранённых организаций
`invoice`	Счёт для компании. Выставляется отдельным методом: `POST /payments/invoices`

Начать пополнение

curl -X POST https://api.aitunnel.ru/v1/aitunnel/payments \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000
  }'

Ответ 201 — платёж в статусе pending:

JSON

{
  "id": 418205731,
  "status": "pending",
  "provider": "tbank",
  "source": "checkout",
  "amount": 2000,
  "bonus_amount": 0,
  "refunded_amount": 0,
  "card_pan": null,
  "payment_url": "https://securepay.tinkoff.ru/new/AbCdEf12",
  "payer_name": null,
  "payer_inn": null,
  "created_at": "2026-11-14T13:16:00.000Z",
  "paid_at": null,
  "receipt_url": null
}

Поле запроса	Смысл
`amount`	Сумма в целых рублях, в пределах `min_amount` и `max_amount` способа. Обязательно
`method`	`card` (по умолчанию), `crypto`, `foreign_card` или `company_sbp`
`company_id`	`id` сохранённой организации, строка UUID. Обязателен для `company_sbp`

Метод не списывает деньги: он открывает платёж и возвращает payment_url. Откройте этот адрес человеку, который платит.
Баланс пополняется, когда платёжная система подтвердит оплату. Проверить — GET /payments/{id}: статус станет succeeded.
После оплаты страница банка возвращает плательщика в кабинет, на страницу пополнения.
У company_sbp в ответе есть ещё объект sbp: qr_image — QR-код ссылки в виде data: URL, due_date — до какого момента ссылку можно оплатить.

Платёж

Поле	Смысл
`id`	Номер платежа, девять цифр
`status`	`pending` — ждёт оплаты, `processing` — оплата в обработке, `succeeded` — оплачен и зачислен, `failed` — отклонён, `expired` — не оплачен вовремя, `refunded` — возвращён
`provider`	Кто проводит платёж: `tbank`, `nowpayments`, `mandarin`, `tbank_b2b_sbp`, `tbank_invoice`
`source`	Как платёж начат: `checkout` — страница оплаты, `saved_card` — списание с сохранённой карты, `auto_recharge` — автопополнение. Бывают ещё `admin` и `partner`
`amount`	Сколько заплачено, ₽
`bonus_amount`	Бонус, начисленный сверху при зачислении, ₽
`refunded_amount`	Сколько возвращено, ₽
`card_pan`	Маска карты (`430000******0777`) или телефон СБП, которыми оплачено. `null`, пока они неизвестны
`payment_url`	Страница оплаты: пока платёж не оплачен, по этому адресу его ещё можно оплатить. `null` у списаний с сохранённой карты
`payer_name`, `payer_inn`	Организация-плательщик. `null` у платежа физического лица
`created_at`, `paid_at`	Когда платёж создан и когда оплачен (`null`, пока не оплачен)
`receipt_url`	Ссылка на кассовый чек, когда он готов, иначе `null`

Список платежей

curl "https://api.aitunnel.ru/v1/aitunnel/payments?limit=20" \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

JSON

{
  "data": [
    {
      "id": 418205731,
      "status": "succeeded",
      "provider": "tbank",
      "source": "checkout",
      "amount": 2000,
      "bonus_amount": 150,
      "refunded_amount": 0,
      "card_pan": "430000******0777",
      "payment_url": "https://securepay.tinkoff.ru/new/AbCdEf12",
      "payer_name": null,
      "payer_inn": null,
      "created_at": "2026-11-14T13:16:00.000Z",
      "paid_at": "2026-11-14T13:17:42.000Z",
      "receipt_url": null
    }
  ],
  "next_cursor": null
}

limit — от 1 до 100, по умолчанию 20.
next_cursor — передайте его в cursor, чтобы получить следующую страницу. null — страница последняя.
Неоплаченные и отклонённые платежи тоже в списке.

Сохранённые карты

GET /payments/cards возвращает карты, сохранённые в банке, с которых можно списывать:

JSON

{
  "data": [
    { "id": "501", "pan": "430000******0777", "exp_date": "1230" }
  ]
}

id — им карта называется в списании и в автопополнении. pan — маска номера, exp_date — срок в виде ММГГ.
POST /payments/cards отвечает { "url": "…" } — страница банка, на которой владелец вводит карту. Номер карты через API не передаётся.
DELETE /payments/cards/{card_id} отвечает 204. Удаление записывается в журнал активности.

Списать с сохранённой карты

curl -X POST https://api.aitunnel.ru/v1/aitunnel/payments/charge \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "card_id": "501"
  }'

JSON

{
  "charged": true,
  "payment": {
    "id": 418205731,
    "status": "succeeded",
    "provider": "tbank",
    "source": "saved_card",
    "amount": 2000,
    "bonus_amount": 0,
    "refunded_amount": 0,
    "card_pan": "430000******0777",
    "payment_url": null,
    "payer_name": null,
    "payer_inn": null,
    "created_at": "2026-11-14T13:16:00.000Z",
    "paid_at": "2026-11-14T13:16:03.000Z",
    "receipt_url": null
  }
}

amount — целые рубли, от 500 до 1 000 000. card_id — из GET /payments/cards.
200 и "charged": true — деньги списаны и уже на балансе.
202 и "charged": false — ответ банка не пришёл. Платёж остаётся pending; чем он закончился, скажет GET /payments/{id}. Не повторяйте списание, пока платёж не завершён.
Банк отклонил списание — 400 с metadata.code charge_declined; на баланс ничего не зачисляется.

Автопополнение

Автопополнение само списывает с сохранённой карты, когда баланс опускается ниже порога. PUT /payments/auto-recharge включает его или меняет настройки:

curl -X PUT https://api.aitunnel.ru/v1/aitunnel/payments/auto-recharge \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "501",
    "threshold": 300,
    "target_amount": 2000,
    "monthly_limit": 10000
  }'

JSON

{
  "enabled": true,
  "card_id": "501",
  "card_pan": "430000******0777",
  "threshold": 300,
  "target_amount": 2000,
  "monthly_limit": 10000,
  "last_error": null,
  "consecutive_failures": 0
}

Поле	Смысл
`enabled`	Включено ли автопополнение
`card_id`, `card_pan`	Карта, с которой идёт списание: её `id` из `GET /payments/cards` и маска номера. В запросе передаётся `card_id`
`threshold`	Порог, ₽: списание запускается, когда баланс опускается ниже. Целое число, не меньше 100
`target_amount`	До какой суммы пополнять баланс, ₽. Целое число от 500 до 1 000 000, больше порога. Списывается разница между этой суммой и балансом, но не меньше 500 ₽
`monthly_limit`	Сколько автопополнение может списать за календарный месяц, ₽. `0` — без лимита. Не передано — остаётся прежним
`last_error`	Почему банк отклонил последнее списание, иначе `null`
`consecutive_failures`	Отказов банка подряд. После третьего автопополнение выключается

GET /payments/auto-recharge возвращает тот же объект. Если автопополнение не настраивали — "enabled": false.
DELETE /payments/auto-recharge выключает его и отвечает 204.
Включение и выключение записываются в журнал активности.

Ошибки

Статус	Смысл
`400`	`invalid_request` — неверное поле (`error.metadata.fields`), сумма вне пределов способа или отказ платёжной системы. `metadata.code`: `payment_method_unavailable` — способ сейчас не предлагается, `payment_provider_refused` — платёжная система не открыла платёж, `charge_declined` — банк отклонил списание с карты (в `metadata.payment_id` — номер платежа)
`401`	`authentication_failed` — ключа нет, он неверный, отозван или истёк
`403`	`permission_denied` — у ключа нет нужного права, IP не в списке разрешённых или метод вызван API-ключом
`404`	`not_found` — «Платеж не найден» или «Карта не найдена»
`503`	`provider_unavailable` — «Платёжная система временно недоступна. Повторите попытку позже.»

400

{
  "error": {
    "code": 400,
    "type": "invalid_request",
    "message": "Минимальная сумма пополнения — 500 ₽",
    "metadata": {
      "fields": [
        { "field": "amount", "message": "Минимальная сумма пополнения — 500 ₽" }
      ]
    },
    "request_id": "req-0J9fQk2vXc8LrT1mNbZa4e"
  }
}