Skip to main content
Recorrência nativaNa 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

FrequênciaIntervaloExemplo
DiáriaTodo diaR$ 1,99/dia
SemanalToda semanaR$ 19,90/semana
MensalTodo mêsR$ 49,90/mês
AnualTodo anoR$ 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.

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

StatusDescrição
activeAssinatura ativa, cobranças em dia
trialingEm período trial, sem cobrança
suspendedTemporariamente suspensa (ex: falha de pagamento)
canceledCancelada pelo cliente ou administrador
revokedRevogada 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 alterar o produto de uma assinatura para um upgrade ou downgrade. A Chargefy calcula o prorate automaticamente.
await chargefy.subscriptions.update(subscriptionId, {
  product_price_id: "price_new_plan",
});
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

EventoQuando
subscription.createdAssinatura criada
subscription.activeAssinatura ativada (após primeiro pagamento ou trial)
subscription.updatedQualquer atualização na assinatura
subscription.canceledAssinatura cancelada
subscription.uncanceledCancelamento revertido
subscription.revokedAssinatura revogada pelo administrador

Comparação com Stripe Subscriptions

Se você está migrando do Stripe, aqui estão as principais diferenças:
ConceitoStripeChargefy
RecorrênciaStripe BillingSistema de recorrência da Chargefy
Métodos de pagamentoMúltiplosApenas Cartão de Crédito
MoedaMúltiplasBRL (Real brasileiro)
InvoicesStripe InvoicesGeração automática Chargefy
ProrationAutomáticoAutomático
Trials
Parcelamento na recorrência❌ (apenas pagamento único)
Saiba mais sobre migração em Migrar para Chargefy.