Référence de l’API : abonnements

Facturation récurrente — une extension par rapport à Crypto Bot. Vous créez une formule (montant + période), envoyez aux utilisateurs son lien d’approbation, et la plateforme les prélève sur le solde de leur portefeuille à chaque période, en créditant le solde de votre application net de frais. Les conventions sont sur la page Référence de l’API marchand.

Le modèle

Une formule est un instantané immuable : le mandat qu’un utilisateur approuve, c’est exactement ce montant pour cette période. Pour changer le prix, créez une nouvelle formule et archivez l’ancienne — les abonnés existants continuent de se renouveler aux conditions qu’ils ont approuvées. La première période est prélevée à l’approbation.

Les renouvellements se facturent automatiquement à la fin de chaque période. Quand un renouvellement échoue (solde insuffisant, compte restreint), l’abonnement passe en grace et la plateforme réessaie toutes les heures pendant la période de grâce (actuellement 48 heures) ; si le prélèvement ne passe toujours pas, l’abonnement devient expired. Les commerçants lisent current_period_end comme la date limite d’accès.

Chaque événement du cycle de vie a un webhook facultatif : subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — permission subscriptions.

Paramètre	Type	Requis	Signification
name	string	oui	1 à 64 caractères, affiché à l’abonné
asset	string	oui	code de l’actif
amount	string	oui	le prélèvement par période, chaîne décimale positive
period_days	integer	oui	période de facturation en jours, du minimum de la plateforme (actuellement 7) à 365

Le résultat est l’objet formule : plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url — le lien t.me que vous envoyez aux utilisateurs pour qu’ils approuvent — et created_at.

Erreurs : 404 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (la fonctionnalité est coupée côté plateforme).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — permission read, aucun paramètre. Renvoie {"items": [plan, …]}, les plus récentes d’abord, chacune avec un champ supplémentaire : active_subscribers — le nombre d’abonnements vivants (active + grace) sur la formule.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — permission subscriptions. Un seul paramètre : plan_id. Arrête les nouvelles approbations ; les abonnements existants continuent de se renouveler sur leur instantané (mettez-y fin un par un avec cancelSubscription). L’archivage ne peut pas être annulé via l’API. Le résultat est l’objet formule mis à jour avec archived: true. Erreur : 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — permission read. Filtres : plan_id, user_id, status (active / grace / cancelled / expired), plus offset / count (500 au maximum). Renvoie {"items": [subscription, …]}, les plus récents d’abord.

L’objet abonnement : subscription_id, plan_id, user_id (l’identifiant Telegram de l’abonné), les conditions de l’instantané (asset, amount, amount_minor, period_days), status, auto_renew, period_no (périodes payées jusqu’ici), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user ou merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — permission subscriptions. Un seul paramètre : subscription_id. Arrête les renouvellements (cancelled_by: "merchant") ; la période payée reste utilisable jusqu’à current_period_end, le statut bascule immédiatement sur cancelled, et l’abonné est prévenu. Un abonné annulé peut ré-approuver plus tard via le même lien de formule. Le résultat est l’objet abonnement mis à jour.

Erreurs : 404 sub_not_found, 409 sub_not_active (déjà annulé ou expiré).