Configurando Recorrência

A recorrência permite cobrar clientes automaticamente em intervalos pré-definidos — mensal, semanal, anual ou personalizado. O sistema gera e cobra faturas automaticamente, sem intervenção manual.

Conceitos

Plano — template reutilizável que define valor, frequência e duração das cobranças
Assinatura — vínculo entre um cliente e um plano; é ela quem gera as cobranças periódicas

Crie um plano de recorrência

Defina valor, intervalo (daily, weekly, monthly, yearly) e número de ciclos. Um plano pode ser vinculado a múltiplos clientes.

Crie uma assinatura

Vincule um cliente (com token de cartão) ao plano. A primeira cobrança é gerada imediatamente.

Receba notificações via webhook

Configure webhooks para `subscription.paid` e `subscription.cancelled` para acompanhar o ciclo de vida das cobranças.

Gerencie o ciclo de vida

Cancele ou pause assinaturas conforme necessário via API.

Passo 1 — Criar um plano

curl --request POST \
  --url "{apiUrl}/plan" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Plano Mensal",
    "amount": 4990,
    "interval": "monthly",
    "interval_count": 1,
    "billing_cycles": 0
  }'

Parâmetros do plano

Campo	Tipo	Descrição
`name`	string	Nome do plano
`amount`	integer	Valor em centavos
`interval`	string	Frequência: `daily`, `weekly`, `monthly`, `yearly`
`interval_count`	integer	Multiplicador do intervalo (ex: `2` + `monthly` = a cada 2 meses)
`billing_cycles`	integer	Número de cobranças (`0` = sem limite)

Passo 2 — Criar uma assinatura

curl --request POST \
  --url "{apiUrl}/subscription" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "plan_id": "ID_DO_PLANO",
    "customer_id": "ID_DO_CLIENTE",
    "card_token": "TOKEN_CARD_DO_CLIENTE"
  }'

[!NOTE] Você também pode criar uma assinatura sem plano usando auto_recurring com valor e frequência definidos diretamente. Não é possível usar plan_id e auto_recurring simultaneamente.

Assinatura sem plano (`auto_recurring`)

const res = await fetch('{apiUrl}/subscription', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customer_id: customerId,
    card_token: cardToken,
    auto_recurring: {
      amount: 2990,
      interval: 'monthly',
      interval_count: 1,
      billing_cycles: 12, // cobrar por 12 meses
    },
  }),
});

Passo 3 — Receber webhooks de recorrência

Configure seu endpoint para tratar os eventos de assinatura:

app.post('/webhook', (req, res) => {
  const { type, data } = req.body;

  switch (type) {
    case 'subscription.paid':
      // Cobrança aprovada — libere acesso ao cliente
      console.log(`Assinatura ${data.subscription_id} cobrada com sucesso`);
      break;

    case 'subscription.overdue':
      // Cobrança falhou — notifique o cliente para atualizar o cartão
      console.log(`Cobrança em atraso para assinatura ${data.subscription_id}`);
      break;

    case 'subscription.cancelled':
      // Assinatura cancelada — revogue o acesso
      console.log(`Assinatura ${data.subscription_id} cancelada`);
      break;
  }

  res.status(200).send('OK');
});

Passo 4 — Cancelar uma assinatura

curl --request DELETE \
  --url "{apiUrl}/subscription/{id}" \
  --header "Authorization: Bearer {token}"

[!TIP] Antes de cancelar, consulte as faturas em aberto com GET /subscription/{id}/invoices para entender o que ainda será cobrado.

Próximos passos

Gerenciando Clientes — cadastre clientes com tokens de cartão
Configurando Webhooks — tratamento completo de eventos
Recorrência — referência completa de planos e assinaturas