Estrutura
Cycle (produto)
Um Cycle é o template do produto recorrente. Define intervalo de cobrança, trial, taxa de setup e configurações de checkout.| Campo | Descrição |
|---|---|
name | Nome do produto |
interval | daily, weekly, monthly, quarterly, semiannual, annual |
interval_count | Multiplicador (ex: 2 = a cada 2 meses) |
trial_days | Dias de trial grátis (0 = sem trial) |
setup_fee | Taxa única de adesão (centavos) |
billing_cycles | Limite de cobranças (null = ilimitado) |
grace_period_days | Dias de tolerância para pagamento (padrão: 3) |
checkout_enabled | Habilita checkout público |
payment_methods | Métodos aceitos (pix, credit_card) |
Plan (plano de preço)
Cada Cycle pode ter múltiplos Plans. Um Plan define o valor da cobrança.| Campo | Descrição |
|---|---|
name | Nome do plano (ex: “Starter”, “Pro”) |
amount | Valor por período (centavos) |
sort_order | Ordem de exibição no checkout |
is_active | Disponível para novas assinaturas |
Subscription (assinatura)
Quando um cliente assina, uma Subscription é criada vinculando o cliente a um Cycle/Plan.Ciclo de vida
| Status | Descrição |
|---|---|
trialing | Em período de trial (sem cobrança) |
active | Assinatura ativa com cobranças em dia |
past_due | Pagamento atrasado (em retry automático) |
suspended | Suspensa após falha nas retentativas |
canceled | Cancelada pelo merchant |
expired | Limite de cobranças atingido |
Cancelamento suave
O cancelamento usacancel_at_period_end: a assinatura continua ativa até o final do período atual, sem gerar nova cobrança.
Invoice (fatura)
Cada período de cobrança gera uma Invoice. A invoice controla o status do pagamento.Ciclo de vida
| Status | Descrição |
|---|---|
draft | Rascunho (antes do processamento) |
open | Cobrança emitida, aguardando pagamento |
paid | Pago com sucesso |
past_due | Vencida |
uncollectible | Falha após 3 tentativas de cobrança |
Composição do valor
| Campo | Descrição |
|---|---|
amount | Valor do plano |
setup_fee | Taxa de adesão (apenas na 1a fatura) |
credit_applied | Crédito do cliente aplicado |
total_amount | Valor final cobrado |
Cobrança automática
O Pagozz executa dois processos automáticos a cada hora:Billing (criação de faturas)
Quandonext_billing_at chega:
- Trial terminou? → Transiciona para
active, gera 1a fatura - Limite atingido? → Transiciona para
expired - Cancelamento agendado? → Transiciona para
canceled - Período normal: → Gera nova fatura, processa pagamento, avança período
Dunning (retentativas)
Quando uma fatura vence sem pagamento:| Tentativa | Quando | Ação |
|---|---|---|
| 1 | No vencimento | Marca como past_due |
| 2 | +3 dias | Retenta cobrança |
| 3 | +5 dias | Retenta cobrança |
| 4 | +7 dias | Última tentativa |
| Após 4 | — | Marca como uncollectible, suspende assinatura |
Eventos de webhook
| Evento | Descrição |
|---|---|
subscription.created | Nova assinatura criada |
subscription.activated | Trial terminou, assinatura ativada |
subscription.past_due | Pagamento atrasado |
subscription.suspended | Suspensa por inadimplência |
subscription.canceled | Cancelada |
subscription.expired | Limite de cobranças atingido |
invoice.created | Nova fatura gerada |
invoice.past_due | Fatura vencida |
invoice.uncollectible | Fatura irrecuperável |
Checkout público
Habilitecheckout_enabled no Cycle para gerar uma URL pública de checkout. O pagador escolhe o plano, informa email e realiza o pagamento.
A URL segue o formato checkout.pagozz.com/{env}_{token}, igual aos links de pagamento.
Para pré-selecionar um plano, use o parâmetro ?plan={plan_id}.