O modelo de 3 camadas
Produto
Um produto marcado como assinatura no dashboard: tipo digital + cobrança recorrente.
Oferta / Plano
Define a frequência (mensal, anual…) e o preço. Gera um
offerSlug.Assinatura
O
ProductSubscription, criado quando a 1ª cobrança é aprovada.Pré-requisitos
1
Configure o produto de assinatura
No dashboard, crie um produto digital + recorrente com um plano (frequência + preço). Guarde o
productId e o offerSlug.2
Autentique-se
Troque sua API key por um token Bearer de curta duração. Veja Autenticação.
3
Tokenize o cartão
Gere um
cardToken (ct_...) em Tokenizar cartão. Ele é de uso pontual e curta duração — tokenize imediatamente antes de iniciar a assinatura.O ciclo de vida
1
Você inicia a assinatura
Chame
POST /v1/subscriptions com productId, offerSlug, o cardToken e o customer. Não envie amountInCents — o valor vem do plano.2
A 1ª cobrança define o resultado
Se aprovada, a assinatura nasce
active e a resposta traz data.subscription. Se recusada, a assinatura não é criada — trate o retry ou peça um novo cartão (veja data.transaction.refuseReason).3
A Ephra assume a recorrência
Um job diário re-cobra o cartão a cada ciclo. Em caso de falha há retentativas automáticas (dunning); após 5 falhas consecutivas a assinatura é cancelada e o acesso é revogado.
Status da assinatura
Frequências do plano
weekly (Semanal), monthly (Mensal), bimonthly (Bimestral), quarterly (Trimestral), semiannual (Semestral), annual (Anual).
Acompanhamento por webhook
Cada cobrança recorrente gera uma nova transação, que dispara os webhooks de transação que você já assina (transaction_paid, transaction_refunded). Use-os para acompanhar cada ciclo — não é preciso ficar consultando a API.
O cancelamento automático após 5 falhas dispara o evento
product_canceled com cancelReason: max_retries.Rotas de assinatura
Iniciar assinatura
Faz a 1ª cobrança e cria a assinatura.
Listar assinaturas
Lista paginada com métricas (MRR, churn, LTV).
Consultar assinatura
Detalhe, cliente e histórico de cobranças.
Cancelar assinatura
Encerra a assinatura e revoga o acesso.