Skip to main content

​
1. Crie um Cycle (produto)

Um Cycle é o template da sua assinatura: define intervalo, trial, taxa de setup e métodos de pagamento. 
curl -X POST https://api.pagozz.com/v1/cycles \
  -H "Content-Type: application/json" \
  -H "Pagozz-Token: pgz_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -d '{
    "name": "SaaS Pro",
    "description": "Acesso completo à plataforma",
    "interval": "monthly",
    "interval_count": 1,
    "trial_days": 7,
    "setup_fee": 0,
    "grace_period_days": 3,
    "checkout_enabled": true,
    "payment_methods": ["pix"]
  }'

​
2. Adicione Plans (planos de preço)

Cada Cycle pode ter um ou mais Plans. O pagador escolhe o plano no checkout. 
# Plan Starter
curl -X POST https://api.pagozz.com/v1/cycles/{cycle_id}/plans \
  -H "Content-Type: application/json" \
  -H "Pagozz-Token: pgz_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -d '{
    "name": "Starter",
    "amount": 2990,
    "sort_order": 1
  }'

# Plan Professional
curl -X POST https://api.pagozz.com/v1/cycles/{cycle_id}/plans \
  -H "Content-Type: application/json" \
  -H "Pagozz-Token: pgz_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -d '{
    "name": "Professional",
    "amount": 5990,
    "sort_order": 2
  }'

​
3. Compartilhe o checkout

Com checkout_enabled: true, o Cycle ganha uma URL pública de checkout. Copie a URL no painel (Cycles → Detalhes → Copiar Link do Checkout) e compartilhe com seus clientes. Para pré-selecionar um plano específico, adicione ?plan={plan_id} à URL.

​
4. Assinante completa o checkout

O pagador:
  1. Acessa a URL do checkout
  2. Escolhe o plano (se houver mais de um)
  3. Informa o email
  4. Seleciona o método de pagamento
  5. Realiza o pagamento (ou inicia trial)

​
Com trial

Se o Cycle tem trial_days > 0:
  • A assinatura é criada com status trialing
  • Nenhuma cobrança é gerada imediatamente
  • Ao final do trial, a primeira fatura é gerada automaticamente

​
Sem trial

Se trial_days = 0:
  • A assinatura é criada com status active
  • A primeira fatura é gerada imediatamente
  • O pagador recebe o QR Code PIX para pagamento

​
5. Receba notificações

Configure webhooks para acompanhar o ciclo de vida: 
const endpoint = await pagozz.webhooks.create({
  url: 'https://meusite.com/webhooks/pagozz',
  events: [
    'subscription.created',
    'subscription.activated',
    'subscription.past_due',
    'subscription.suspended',
    'subscription.canceled',
    'invoice.created',
    'invoice.past_due',
  ],
});

​
Eventos principais

EventoQuando usar
subscription.createdLiberar acesso (trial ou primeiro pagamento)
subscription.activatedTrial terminou, primeiro pagamento confirmado
subscription.past_dueEnviar lembrete de pagamento
subscription.suspendedBloquear acesso
subscription.canceledLimpar recursos do cliente

​
Exemplo completo com SDK

import { Pagozz } from '@pagozz/sdk';

const pagozz = new Pagozz('pgz_test_XXXXXXXXXXXXXXXXXXXXXXXX');

// 1. Criar Cycle
const cycle = await pagozz.cycles.create({
  name: 'Plano Mensal',
  interval: 'monthly',
  interval_count: 1,
  trial_days: 7,
  checkout_enabled: true,
  payment_methods: ['pix'],
});

// 2. Criar Plan
const plan = await pagozz.cycles.createPlan(cycle.id, {
  name: 'Básico',
  amount: 2990,
});

// 3. Compartilhar URL do checkout (obtida via painel ou API)
console.log(`Checkout: ${cycle.checkout_url}`);

// 4. Listar assinaturas ativas
const { subscriptions } = await pagozz.cycles.list({
  status: 'active',
});

// 5. Cancelar uma assinatura
await pagozz.cycles.cancel(subscription.id, {
  reason: 'Customer requested',
});
// A assinatura continuará ativa até o final do período

​
Intervalos disponíveis

IntervaloDescriçãoExemplo
dailyDiárioA cada dia
weeklySemanalA cada semana
monthlyMensalA cada mês
quarterlyTrimestralA cada 3 meses
semiannualSemestralA cada 6 meses
annualAnualA cada ano
Use interval_count para multiplicar: interval: 'monthly' + interval_count: 2 = a cada 2 meses.