Referencia de la API: suscripciones

Cobros recurrentes: una extensión sobre Crypto Bot. Creas un plan (monto + período), les envías a los usuarios su enlace de aprobación y la plataforma les cobra del saldo de su billetera cada período, acreditando el saldo de tu app neto de comisión. Las convenciones están en la página de referencia de la API para comerciantes.

El modelo

Un plan es una foto inmutable: el mandato que aprueba un usuario es exactamente este monto por este período. Para cambiar el precio, crea un plan nuevo y archiva el viejo; quienes ya están suscritos siguen renovando con las condiciones que aprobaron. El primer período se cobra al aprobarlo.

Las renovaciones se cobran solas al final de cada período. Cuando una renovación falla (saldo insuficiente, cuenta restringida), la suscripción entra en grace y la plataforma reintenta cada hora dentro del período de gracia (hoy 48 horas); si aun así no logra cobrar, la suscripción pasa a expired. Los comerciantes leen current_period_end como la fecha límite del acceso.

Cada evento del ciclo de vida tiene un webhook opcional: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — ámbito subscriptions.

Parámetro	Tipo	Obligatorio	Significado
name	string	sí	de 1 a 64 caracteres, se le muestra a quien se suscribe
asset	string	sí	código del activo
amount	string	sí	el cobro por período, cadena decimal positiva
period_days	integer	sí	período de cobro en días, desde el mínimo de la plataforma (hoy 7) hasta 365

El resultado es el objeto de plan: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url —el enlace de t.me que les envías a los usuarios para aprobar— y created_at.

Errores: 404 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (la función está apagada del lado de la plataforma).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — ámbito read, sin parámetros. Devuelve {"items": [plan, …]}, los más recientes primero, cada uno con un campo extra: active_subscribers, la cantidad de suscripciones vivas (active + grace) del plan.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — ámbito subscriptions. Un parámetro: plan_id. Detiene las aprobaciones nuevas; las suscripciones existentes siguen renovando con su foto (termínalas una a una con cancelSubscription). Archivar no se puede deshacer por la API. El resultado es el objeto de plan actualizado con archived: true. Error: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — ámbito read. Filtros: plan_id, user_id, status (active / grace / cancelled / expired), más offset / count (máx. 500). Devuelve {"items": [subscription, …]}, las más recientes primero.

El objeto de suscripción: subscription_id, plan_id, user_id (el id de Telegram de quien se suscribe), las condiciones de la foto (asset, amount, amount_minor, period_days), status, auto_renew, period_no (períodos pagados hasta ahora), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user o merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — ámbito subscriptions. Un parámetro: subscription_id. Detiene las renovaciones (cancelled_by: "merchant"); el período pagado sigue siendo usable hasta current_period_end, el estado pasa a cancelled de inmediato y se le avisa a quien estaba suscrito. Alguien que canceló puede volver a aprobar más adelante por el mismo enlace del plan. El resultado es el objeto de suscripción actualizado.

Errores: 404 sub_not_found, 409 sub_not_active (ya cancelada o expirada).