Довідник API: підписки

Регулярні платежі — розширення над Crypto Bot. Ви створюєте план (сума + період), надсилаєте користувачам посилання на підтвердження, і платформа списує оплату з балансу їхнього гаманця кожного періоду, зараховуючи її на баланс застосунку за вирахуванням комісії. Загальні правила — на сторінці Довідник Мерчант 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 (уже скасована або закінчилася).