API reference: subscriptions

Recurring billing — Crypto Bot ke upar ek extension. Aap ek plan banate hain (amount + period), users ko uska approval link bhejte hain, aur platform har period unke wallet balance se charge karta hai aur fee kaat kar aapke app balance mein credit kar deta hai. Conventions Merchant API reference page par hain.

Model

Plan ek immutable snapshot hota hai: user jo mandate approve karta hai wo theek isi amount aur isi period ka hota hai. Price badalne ke liye naya plan banayein aur purana archive karein — maujooda subscribers unhi terms par renew hote rehte hain jo unhone approve ki thi. Pehla period approval par hi charge hota hai.

Har period ke ant mein renewal apne aap charge hota hai. Renewal fail ho (kam balance, restricted account) to subscription grace mein jaati hai aur platform grace period ke dauraan har ghante retry karta hai (iski avadhi platform tay karta hai). Tab bhi payment na ho paaye to subscription expired ho jaati hai. Merchants access ki deadline ke liye current_period_end dekhein.

Har lifecycle event ka ek opt-in webhook hai: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — scope subscriptions.

Parameter	Type	Zaroori	Matlab
name	string	haan	1–64 characters, subscriber ko dikhta hai
asset	string	haan	Asset code
amount	string	haan	Har period ka charge, positive decimal string
period_days	integer	haan	Billing period, dinon mein: platform ke minimum se 365 tak (bahut chhota ho to invalid_period mein minimum milta hai)

Result plan object hota hai: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url — wo t.me link jo aap users ko approve karne ke liye bhejte hain — aur created_at.

Errors: 400 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (feature available nahi hai) aur 409 too_many_plans (naya plan banaane se pehle unused plan archive karein).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — scope read, koi parameters nahi. {"items": [plan, …]} deta hai, sabse naya pehle, har ek ke saath ek extra field: active_subscribers — us plan par live (active + grace) subscriptions ki ginti.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — scope subscriptions. Ek parameter: plan_id. Naye approvals rok deta hai; maujooda subscriptions apne snapshot par renew hoti rehti hain (unhe ek-ek karke cancelSubscription se khatam karein). Archive karne ko API se undo nahi kiya ja sakta. Result archived: true ke saath updated plan object hota hai. Error: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — scope read. Filters: plan_id, user_id, status (active / grace / cancelled / expired), aur saath mein offset / count (max 500). {"items": [subscription, …]} deta hai, sabse naya pehle.

subscription object: subscription_id, plan_id, user_id (subscriber ka Telegram ID), snapshot terms (asset, amount, amount_minor, period_days), status, auto_renew, period_no (ab tak pay ho chuke periods), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user ya merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — scope subscriptions. Ek parameter: subscription_id. Renewals rokta hai (cancelled_by: "merchant"); paid period current_period_end tak available rahta hai, status turant cancelled ho jaata hai aur subscriber ko notification milta hai. Plan aur app available hon to canceled subscriber usi link se dobara approve kar sakta hai. Dobara approval par turant charge lagta hai aur naya period shuru hota hai. Result updated subscription object hai.

Errors: 404 sub_not_found, 409 sub_not_active (pehle hi cancel ya expire ho chuki).