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 un conjunto de condiciones fijas: el usuario autoriza el cobro del monto indicado con la periodicidad establecida. 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 (cuya duración establece la plataforma); 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 (indicado por invalid_period si el período es demasiado corto) 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: 400 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (la función no está disponible) y 409 too_many_plans (archiva un plan que no uses antes de crear otro).

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 vigentes (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 las condiciones que aprobaron (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 aprobadas (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 dando acceso hasta current_period_end, el estado pasa a cancelled de inmediato y se le avisa a quien estaba suscrito. Un usuario que canceló puede volver a autorizar la suscripción por el mismo enlace mientras el plan y la app sigan disponibles. La nueva autorización cobra de inmediato e inicia un nuevo período. El resultado es el objeto de suscripción actualizado.

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