Платежи
Пополнить баланс, посмотреть платежи, списать с сохранённой карты и настроить автопополнение через API.
Сам баланс отдаёт 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:charge | Начать привязку карты. В ответе — адрес страницы банка |
DELETE /payments/cards/{card_id} | billing:charge | Удалить сохранённую карту |
POST /payments/charge | billing:charge | Пополнить с сохранённой карты, сразу |
GET /payments/auto-recharge | billing:read | Настройки автопополнения |
PUT /payments/auto-recharge | billing:charge | Включить автопополнение или изменить его |
DELETE /payments/auto-recharge | billing:write | Выключить автопополнение |
Что открывают права
| Право | Смысл |
|---|---|
billing:read | Только смотреть: баланс, платежи и их статус, способы оплаты, сохранённые карты (маска номера), настройки автопополнения |
billing:write | Просить заплатить: открыть платёж и получить ссылку на страницу оплаты, выставить счёт, вести организации и ЭДО, выключить автопополнение. Деньги не списывает — платит сам владелец. Включает billing:read |
billing:charge | Тратить деньги владельца без него: списать с сохранённой карты любую сумму в пределах лимитов, включить или изменить автопополнение, привязать и удалить карту. Включает billing:write. Выдаётся только в кабинете: приложению через вход через AITunnel его не получить |
Способы оплаты
curl https://aitunnel.83.141.93.205.nip.io/__api/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://aitunnel.83.141.93.205.nip.io/__api/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://aitunnel.83.141.93.205.nip.io/__api/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://aitunnel.83.141.93.205.nip.io/__api/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.codecharge_declined; на баланс ничего не зачисляется.
Автопополнение
Автопополнение само списывает с сохранённой карты, когда баланс опускается ниже порога. PUT /payments/auto-recharge включает его или меняет настройки:
curl -X PUT https://aitunnel.83.141.93.205.nip.io/__api/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"
}
}