Assinaturas & Recorrência

Gerencie cobranças recorrentes com o sistema de recorrência da Chargefy

Recorrência nativa

Na Chargefy, assinaturas são gerenciadas pelo sistema de recorrência nativo da plataforma. Ao criar um produto com preço recorrente e um cliente confirmar o checkout com cartão de crédito, a Chargefy automaticamente configura o plano de recorrência.

​

Visão Geral

Uma assinatura na Chargefy representa uma relação contínua de cobrança entre um cliente e um produto. Diferente de pagamentos únicos, assinaturas cobram automaticamente o cliente em intervalos regulares.

​

Frequências suportadas

O preço carrega interval + interval_count:

Frequência	interval	interval_count	Exemplo
Diária	day	1	R$ 1,99/dia
Semanal	week	1	R$ 19,90/semana
Quinzenal	week	2	R$ 34,90 a cada 2 semanas
Mensal	month	1	R$ 49,90/mês
Trimestral	month	3	R$ 129,90 a cada 3 meses
Semestral	month	6	R$ 239,90 a cada 6 meses
Anual	year	1	R$ 399,90/ano

Assinaturas são cobradas exclusivamente via cartão de crédito. PIX e Boleto não suportam cobranças recorrentes automáticas. interval_count > 1 está no schema mas a integração Zoop honra apenas 1 por ora (roadmap).

​

Quantidade na assinatura

Cada linha de assinatura (subscription_product_prices) carrega um campo quantity (default 1). O total cobrado por ciclo é unit_amount × quantity.

Use pra cobrar por assento, por licença, ou por unidade. Ver Precificação por Quantidade.

// Upgrade de 5 pra 10 assentos
await chargefy.subscriptions.update(subscriptionId, {
  quantity: 10,
})
// Próxima cobrança: unit_amount * 10

​

Como funciona

​

Criação de assinatura

1. Produto recorrente

   Crie um produto com ciclo de cobrança recorrente (mensal, anual, semanal ou diário) no dashboard ou via API.

2. Checkout

   O cliente acessa o checkout (via link, embed ou API) e seleciona cartão de crédito como método de pagamento.

3. Primeira cobrança

   Ao confirmar o checkout, a Chargefy processa a primeira cobrança e cria um plano de recorrência automaticamente.

4. Cobranças automáticas

   A Chargefy cobra automaticamente o cartão do cliente no intervalo definido, atualizando o status a cada cobrança.

​

Fluxo técnico

Cliente confirma checkout
    ↓
Chargefy processa a primeira cobrança
    ↓
Chargefy cria plano de recorrência
    ↓
Cobranças automáticas no ciclo definido
    ↓
Chargefy atualiza status e dispara eventos

​

Ciclo de vida da assinatura

Criada → Ativa → Suspensa → Cancelada
           ↑        ↓
           └── Reativada

​

Status

Status	Descrição
active	Assinatura ativa, cobranças em dia
trialing	Em período trial, sem cobrança
suspended	Temporariamente suspensa (ex: falha de pagamento)
canceled	Cancelada pelo cliente ou administrador
revoked	Revogada pelo administrador

​

Gerenciamento

​

Suspender assinatura

Pausa temporariamente as cobranças sem cancelar a assinatura. O cliente perde acesso aos benefícios durante a suspensão.

await chargefy.subscriptions.update(subscriptionId, {
  status: "suspended",
});

​

Reativar assinatura

Retoma as cobranças de uma assinatura suspensa. O cliente recupera acesso aos benefícios.

await chargefy.subscriptions.update(subscriptionId, {
  status: "active",
});

​

Cancelar assinatura

Cancela permanentemente a assinatura. O cliente mantém acesso até o final do período já pago.

await chargefy.subscriptions.cancel(subscriptionId, {
  cancel_at_period_end: true, // Cancela no final do período atual
});

Com cancel_at_period_end: true, o cliente mantém acesso até a data de renovação. Com false, o cancelamento é imediato.

​

Alterar plano (Upgrade/Downgrade)

Você pode trocar o preço de uma assinatura pra um upgrade ou downgrade. A Chargefy calcula o prorate automaticamente.

await chargefy.subscriptions.update(subscriptionId, {
  product_price_id: "price_new_plan",
});

Ou ajustar a quantity sem trocar de preço (mesmo plano, mais/menos assentos):

await chargefy.subscriptions.update(subscriptionId, {
  quantity: 8, // era 5
})

Saiba mais nos guias de Upgrade e Downgrade.

​

Período Trial

Assinaturas podem ter um período trial onde o cliente não é cobrado. Ao final do trial, a primeira cobrança é processada automaticamente.

• O trial é configurado no produto (ex: 7 dias, 14 dias, 1 mês)
• O cliente precisa fornecer dados do cartão no checkout
• Se o cliente cancelar durante o trial, não há cobrança

Saiba mais em Trials.

​

Faturamento automático

A cada ciclo de cobrança, a Chargefy automaticamente:

1. Processa a cobrança no cartão
2. Cria um registro de transação (zoop_transaction)
3. Dispara webhooks (subscription.updated, checkout.updated)
4. Atualiza o acesso do cliente aos benefícios

Em caso de falha na cobrança, a Chargefy tenta novamente automaticamente conforme configuração de retry.

​

Webhook events

Evento	Quando
subscription.created	Assinatura criada
subscription.active	Assinatura ativada (após primeiro pagamento ou trial)
subscription.updated	Qualquer atualização na assinatura
subscription.canceled	Assinatura cancelada
subscription.uncanceled	Cancelamento revertido
subscription.revoked	Assinatura revogada pelo administrador

​

Comparação com Stripe Subscriptions

Se você está migrando do Stripe, aqui estão as principais diferenças:

Conceito	Stripe	Chargefy
Recorrência	Stripe Billing	Sistema de recorrência da Chargefy
Métodos de pagamento	Múltiplos	Apenas Cartão de Crédito
Moeda	Múltiplas	BRL (Real brasileiro)
Invoices	Stripe Invoices	Geração automática Chargefy
Proration	Automático	Automático
Trials	✅	✅
Parcelamento na recorrência	❌	❌ (apenas pagamento único)

Saiba mais sobre migração em Migrar para Chargefy.