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 après déduction des frais. Les conventions sont sur la page Référence de l’API marchand.

Le modèle

Une formule définit des conditions fixes : l’utilisateur autorise le prélèvement de ce montant précis pour cette période. Pour changer le prix, créez une nouvelle formule et archivez l’ancienne — les abonnements 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 (dont la durée est définie par la plateforme) ; si le prélèvement ne passe toujours pas, l’abonnement devient expired. Les marchands utilisent current_period_end comme date limite d’accès. Si le renouvellement est prélevé pendant grace, la période suivante commence au current_period_end précédent, et non au moment du paiement.

Les événements du cycle de vie ont des webhooks facultatifs : subscription_activated, subscription_charged, subscription_cancelled, subscription_expired. Le passage en grace n’a pas de webhook (l’abonné reçoit un message dans Telegram) ; si vous en avez besoin, interrogez getSubscriptions avec status=grace. Si votre application est supprimée, ses abonnements sont annulés au renouvellement suivant avec cancelled_by: "merchant".

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 (indiqué par invalid_period lorsque la période est trop courte) à 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 : 400 unknown_asset, 400 invalid_amount, 409 invalid_period (période inférieure au minimum de la plateforme), 400 invalid_request (period_days absent, non positif ou supérieur à 365 ; également si name, asset ou amount est absent), 503 subs_disabled (fonction indisponible) et 409 too_many_plans (50 formules non archivées au maximum — archivez une formule inutilisée avant d’en créer une autre).

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 en cours (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 aux conditions approuvées (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 (100 par défaut, 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 approuvées (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 utilisateur dont l’abonnement a été annulé peut souscrire de nouveau via le même lien tant que la formule et l’application restent disponibles. Cette nouvelle souscription entraîne un prélèvement immédiat et démarre une nouvelle période. Le résultat est l’objet abonnement mis à jour.

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