Справочник API: подписки

Регулярные платежи — расширение над Crypto Bot. Вы создаёте план (сумма + период), отправляете пользователям ссылку на подтверждение, и платформа списывает оплату с баланса их кошелька каждый период, зачисляя её на баланс приложения за вычетом комиссии. Общие правила — на странице Справочник Merchant API.

Модель

План — это неизменяемый снимок: пользователь соглашается ровно на эту сумму за этот период. Чтобы изменить цену, создайте новый план и заархивируйте старый — у существующих подписчиков подписка продлевается на тех условиях, которые они подтвердили. Плата за первый период списывается при подтверждении.

Плата за продление списывается автоматически в конце каждого периода. Когда продление не проходит (не хватает средств, на аккаунте ограничения), подписка переходит в grace, и платформа повторяет попытки ежечасно в пределах льготного периода (сейчас 48 часов); если списать так и не удалось, подписка становится expired. Срок, до которого у подписчика есть доступ, мерчант берёт из current_period_end.

У каждого события жизненного цикла есть включаемый по желанию вебхук: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — право subscriptions.

Параметр	Тип	Обязателен	Значение
name	string	да	1–64 символа, показывается подписчику
asset	string	да	код актива
amount	string	да	сумма списания за период, положительная десятичная строка
period_days	integer	да	период в днях, от платформенного минимума (сейчас 7) до 365

Результат — объект плана: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url — ссылка t.me, которую вы отправляете пользователям для подтверждения, — и created_at.

Ошибки: 404 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (функция отключена на стороне платформы).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — право read, без параметров. Возвращает {"items": [план, …]}, новые первыми, каждый с одним дополнительным полем: active_subscribers — число действующих (active + grace) подписок плана.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — право subscriptions. Один параметр: plan_id. Останавливает новые подтверждения; существующие подписки продолжают продлеваться на зафиксированных условиях (завершайте их по одной через cancelSubscription). Отменить архивирование через API нельзя. Результат — обновлённый объект плана с archived: true. Ошибка: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — право read. Фильтры: plan_id, user_id, status (active / grace / cancelled / expired), плюс offset / count (максимум 500). Возвращает {"items": [подписка, …]}, новые первыми.

Объект подписки: subscription_id, plan_id, user_id (Telegram ID подписчика), зафиксированные условия (asset, amount, amount_minor, period_days), status, auto_renew, period_no (число оплаченных периодов), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user или merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — право subscriptions. Один параметр: subscription_id. Останавливает продления (cancelled_by: "merchant"); оплаченный период действует до current_period_end, статус сразу становится cancelled, подписчик получает уведомление. После отмены подписчик может позже снова оформить подписку по той же ссылке плана. Результат — обновлённый объект подписки.

Ошибки: 404 sub_not_found, 409 sub_not_active (уже отменена или истекла).