Referência da API: assinaturas

Cobrança recorrente — uma extensão sobre o Crypto Bot. Você cria um plano (valor + período), manda aos usuários o link de aprovação dele, e a plataforma cobra dessas pessoas, com o saldo da carteira delas, a cada período, creditando o saldo do seu app já líquido de taxa. As convenções estão na página da referência da API para comerciantes.

O modelo

Um plano é um retrato imutável: o mandato que o usuário aprova é exatamente este valor por este período. Para mudar o preço, crie um plano novo e arquive o antigo — quem já assina continua renovando nos termos que aprovou. O primeiro período é cobrado na aprovação.

As renovações são cobradas automaticamente no fim de cada período. Quando uma renovação falha (saldo insuficiente, conta restrita), a assinatura entra em grace e a plataforma tenta de novo a cada hora dentro do período de carência (hoje, 48 horas); se ainda assim não conseguir cobrar, a assinatura vira expired. Os comerciantes leem o current_period_end como o prazo do acesso.

Todo evento do ciclo de vida tem um webhook opcional: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — escopo subscriptions.

Parâmetro	Tipo	Obrigatório	O que significa
name	string	sim	de 1 a 64 caracteres, mostrado a quem assina
asset	string	sim	código do ativo
amount	string	sim	a cobrança por período, string decimal positiva
period_days	integer	sim	período de cobrança em dias, do mínimo da plataforma (hoje, 7) até 365

O resultado é o objeto de plano: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url — o link t.me que você manda para os usuários aprovarem — e created_at.

Erros: 404 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (o recurso está desligado do lado da plataforma).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — escopo read, sem parâmetros. Devolve {"items": [plan, …]}, dos mais novos para os mais antigos, cada um com um campo a mais: active_subscribers — a contagem de assinaturas vivas (active + grace) naquele plano.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — escopo subscriptions. Um parâmetro: plan_id. Interrompe as novas aprovações; as assinaturas existentes continuam renovando pelo retrato delas (encerre uma a uma com cancelSubscription). Arquivar não pode ser desfeito pela API. O resultado é o objeto de plano atualizado, com archived: true. Erro: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — escopo read. Filtros: plan_id, user_id, status (active / grace / cancelled / expired), além de offset / count (máx. 500). Devolve {"items": [subscription, …]}, dos mais novos para os mais antigos.

O objeto de assinatura: subscription_id, plan_id, user_id (o id do Telegram de quem assina), os termos do retrato (asset, amount, amount_minor, period_days), status, auto_renew, period_no (períodos pagos até agora), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user ou merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — escopo subscriptions. Um parâmetro: subscription_id. Interrompe as renovações (cancelled_by: "merchant"); o período pago continua utilizável até o current_period_end, o status muda para cancelled na hora, e quem assina é avisado. Quem teve a assinatura cancelada pode aprovar de novo depois, pelo mesmo link do plano. O resultado é o objeto de assinatura atualizado.

Erros: 404 sub_not_found, 409 sub_not_active (já cancelada ou expirada).