Visao geral do fluxo
Pre-requisitos
- Node.js 18+
- Uma conta Chargefy com Organization Access Token
- SDK instalado:
@chargefy/sdk - Ambiente de sandbox configurado para testes
src/lib/chargefy.ts
Passo 1: Criar produto com preco recorrente
O primeiro passo e criar um produto que tenha pelo menos um preco com tiporecurring. A Chargefy suporta as seguintes frequencias de cobranca:
| Frequencia | recurringInterval | Uso comum |
|---|---|---|
| Diaria | day | Trials, servicos por demanda |
| Semanal | week | Servicos semanais |
| Mensal | month | SaaS, streaming, planos gerais |
| Anual | year | Descontos para pagamento anual |
Via SDK
Via cURL
Criar produto com periodo de trial
Passo 2: Criar checkout para produto de assinatura
Quando o cliente escolhe um plano, crie uma sessao de checkout usando oproductPriceId do preco recorrente.
Via SDK
Via cURL
A Chargefy detecta automaticamente que o preco e recorrente e configura o checkout para criar uma assinatura apos o pagamento.
Passo 3: Processar primeiro pagamento
A primeira cobranca da assinatura e processada no checkout. O cliente pode pagar via PIX ou Cartao de Credito.Pagamento via PIX
Pagamento via Cartao de Credito
Passo 4: Plano de recorrencia (automatico)
Apos o primeiro pagamento ser confirmado, a Chargefy automaticamente:- Cria um plano de recorrencia com a frequencia e valor definidos no preco
- Vincula o metodo de pagamento do cliente (cartao tokenizado ou conta PIX) ao plano
- Agenda as cobranças futuras de acordo com o intervalo configurado
- Emite o webhook
subscription.createdseguido desubscription.active
Para assinaturas com PIX, a Chargefy gera automaticamente um novo QR Code a cada ciclo e envia por email ao cliente. Para cartao de credito, a cobranca e processada automaticamente usando o cartao tokenizado.
Gerenciamento de assinaturas
Listar assinaturas de um cliente
Obter detalhes de uma assinatura
Upgrade de plano (com prorata)
Quando um cliente faz upgrade para um plano superior, a Chargefy calcula automaticamente o valor proporcional (prorata) restante do periodo atual e cobra a diferenca.Downgrade de plano
No downgrade, o novo preco entra em vigor no proximo ciclo de cobranca, sem cobranca adicional no periodo atual.Suspender assinatura
A suspensao interrompe temporariamente as cobranças sem cancelar a assinatura. Util para clientes com pagamento falho ou que solicitam uma pausa.Reativar assinatura suspensa
Cancelar assinatura
A Chargefy suporta dois modos de cancelamento:Cancelamento ao final do periodo (recomendado)
O cliente mantem acesso ate o fim do periodo ja pago. E o padrao mais justo e reduz chargebacks.Cancelamento imediato
O acesso e revogado imediatamente. Use apenas em casos de fraude, violacao de termos ou solicitacao explicita.Reverter cancelamento agendado
Se o cliente mudar de ideia antes do fim do periodo:Webhooks de assinatura
Configure um endpoint de webhooks para reagir aos eventos do ciclo de vida da assinatura. Veja o guia de webhooks para setup completo.Eventos disponíveis
| Evento | Quando ocorre |
|---|---|
subscription.created | Assinatura criada apos primeiro pagamento |
subscription.active | Assinatura ativada (primeiro pagamento confirmado) |
subscription.updated | Alteracao de plano, preco ou metadados |
subscription.canceled | Assinatura cancelada (imediato ou ao fim do periodo) |
subscription.revoked | Acesso revogado (apos fim do periodo de assinatura cancelada) |
Implementacao do handler
src/routes/webhooks.ts
Gerenciamento de faturas
Cada cobranca recorrente gera uma fatura (invoice). Voce pode consultar o historico de faturas do cliente.Listar faturas de uma assinatura
Consultar fatura especifica
Exemplo completo: Sistema SaaS de assinaturas
Um exemplo funcional com backend Express e dashboard React.Backend (Express)
src/routes/subscriptions.ts
Dashboard React
src/components/SubscriptionDashboard.tsx
Boas praticas
Periodo de graca (grace period)
Configure um periodo de graca para lidar com falhas temporarias de pagamento antes de suspender o acesso.Dunning (recuperacao de receita)
Estrategia recomendada para tentativas de cobranca:| Tentativa | Dias apos falha | Acao |
|---|---|---|
| 1a retentativa | +3 dias | Email amigavel + nova tentativa automatica |
| 2a retentativa | +7 dias | Email urgente + link para atualizar pagamento |
| 3a retentativa | +14 dias | Suspensao do acesso + email de suspensao |
| Cancelamento | +30 dias | Cancelamento definitivo se nao regularizado |
Tratamento de pagamento falho
Testando assinaturas no sandbox
O ambiente de sandbox permite testar todo o fluxo de assinatura sem cobranças reais.Configurar cliente para sandbox
Cartoes de teste
| Cartao | Comportamento |
|---|---|
4111 1111 1111 1111 | Pagamento aprovado |
4000 0000 0000 0002 | Pagamento recusado |
4000 0000 0000 0069 | Pagamento expirado |
4000 0000 0000 0077 | Erro de processamento |
Simular ciclo completo
Proximos passos
Checkout Embed
Integre o checkout diretamente na sua pagina.
Webhooks
Configuracao completa de endpoints de webhook.
Gerenciamento de clientes
API de clientes e portal do assinante.
Reembolsos
Como processar reembolsos de cobranças recorrentes.

