Assinatura recorrente

Fluxo para SaaS e planos mensais: você cadastra o plano uma vez, assina o cliente e a Upag gera uma fatura a cada período e cobra pelo método da assinatura. Você acompanha tudo por webhooks.

Os exemplos usam o sandbox (https://api.upag.dev/v1) com sk_test_…. Em produção use https://api.upag.io/v1 com sk_live_….

1. Criar produto e preço recorrente

Valores em centavos (mínimo 100). A resposta de Criar produto traz só o produto; o preço é lido em Listar preços. Se preferir, crie o produto sem defaultPrice e use Criar preço, que devolve o preço direto.

curl -X POST https://api.upag.dev/v1/products/0b9c1f3e-6a4d-4c1e-9d55-3f1f6a7c2e10/prices \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mensal",
    "amount": 4990,
    "currency": "brl",
    "billingType": "recurring",
    "interval": "month",
    "intervalCount": 1
  }'

import { Upag } from 'upag';

const upag = new Upag('sk_test_your_api_key');

const product = await upag.products.create({
  name: 'Plano Pro',
  description: 'Acesso completo à plataforma',
});

const price = await upag.prices.create(product.id, {
  name: 'Mensal',
  amount: 4990,
  currency: 'brl',
  billingType: 'recurring',
  interval: 'month',
  intervalCount: 1,
});

2. Criar o cliente

curl -X POST https://api.upag.dev/v1/customers \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "email": "maria@example.com",
    "document": { "type": "cpf", "number": "12345678909" }
  }'

const customer = await upag.customers.create({
  name: 'Maria Souza',
  email: 'maria@example.com',
  document: { type: 'cpf', number: '12345678909' },
});

3. Criar a assinatura

Escolha o método de cobrança. Os dois dependem do cliente do passo 2.

Pix

Não precisa de nada além do cliente e do preço. A assinatura nasce incomplete e vira active quando o cliente paga a fatura do primeiro período.

curl -X POST https://api.upag.dev/v1/subscriptions \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83",
    "paymentMethod": "pix",
    "items": [{ "price": "3a7e9c14-6b2d-4f85-9e10-5c8d2a7b4f61" }]
  }'

const subscription = await upag.subscriptions.create({
  customer: customer.id,
  paymentMethod: 'pix',
  items: [{ price: price.id }],
});

Para pegar o QR code do primeiro período, liste as faturas do cliente (status=open), ache a de subscription igual ao ID e leia a cobrança em payments[].charge (Obter cobrança). Nas renovações, cada fatura nova traz um QR code com vencimento de 3 dias.

Cartão

POST /subscriptions com paymentMethod: "card" exige um cartão ativo que já pertença ao cliente. Um cartão recém-tokenizado (Criar cartão) não pertence a ninguém; ele passa a ser do cliente quando é usado numa cobrança de cartão do cliente (Criar cobrança) ou numa confirmação de checkout. Usá-lo antes disso devolve 404 SUBSCRIPTION_CARD_NOT_FOUND. Por isso, para o primeiro cartão de um cliente, o caminho é o checkout: crie um link de pagamento com o preço recorrente e deixe o pagador confirmar com o cartão. A confirmação cria a fatura, cobra, vincula o cartão ao cliente e cria a assinatura. Depois disso o cartão fica na conta do cliente:

Node.js SDK

const { data: cards } = await upag.cards.list({ customer: customer.id });

e pode ser usado em novas assinaturas:

curl -X POST https://api.upag.dev/v1/subscriptions \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83",
    "paymentMethod": "card",
    "card": "5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15",
    "items": [{ "price": "3a7e9c14-6b2d-4f85-9e10-5c8d2a7b4f61", "quantity": 1 }]
  }'

const subscription = await upag.subscriptions.create({
  customer: customer.id,
  paymentMethod: 'card',
  card: cards[0].id,
  items: [{ price: price.id, quantity: 1 }],
});

Com cartão aprovado, a resposta já volta active. Se o cartão for recusado, a criação não falha: a assinatura fica incomplete. Todos os campos e erros: Criar assinatura.

4. Acompanhar por webhook

Valide a assinatura do webhook (upag.webhooks.validateSignature sobre o corpo cru, veja Segurança) e reaja aos eventos:

Evento	O que fazer
`subscription.active`	Liberar o acesso
`invoice.paid`	Registrar o pagamento do período
`subscription.past_due`	A renovação falhou: avise o cliente; a Upag tenta de novo
`subscription.canceled`	Revogar o acesso

Node.js SDK

app.post('/webhooks/upag', express.raw({ type: '*/*' }), async (req, res) => {
  const valid = upag.webhooks.validateSignature(
    req.body,
    req.headers['x-webhook-signature'],
    process.env.UPAG_WEBHOOK_SECRET,
  );
  if (!valid) return res.sendStatus(401);

  const { event, data } = JSON.parse(req.body.toString('utf8'));

  if (event === 'subscription.active') await grantAccess(data.customer);
  if (event === 'subscription.canceled') await revokeAccess(data.customer);

  return res.sendStatus(200);
});

Payloads: assinatura e fatura.

Renovações

A cada período a Upag cria a fatura e cobra: no cartão, à vista, e no Pix, com um novo QR code de 3 dias. Se a cobrança falhar, a assinatura vai para past_due e novas tentativas são feitas. Para ver o valor da próxima fatura antes de ela existir, use Fatura futura:

Node.js SDK

const preview = await upag.invoices.upcoming({ subscription: subscription.id });

Mudar itens

Adicionar, alterar ou remover itens não gera fatura nem proporcional. Com applyAt: 'now' a mudança vale já; com 'period_end' ela fica agendada e é aplicada na renovação.

Node.js SDK

// Agenda um item extra para a próxima renovação
await upag.subscriptions.createItem(subscription.id, {
  price: addonPrice.id,
  quantity: 1,
  applyAt: 'period_end',
});

Veja Criar item, Atualizar item, Remover item e as mudanças agendadas.

Cancelar

Por padrão o cancelamento é imediato. Para manter o acesso até o fim do período já pago, use atPeriodEnd:

curl -X POST https://api.upag.dev/v1/subscriptions/9a3c6e1f-0d58-4b72-a4e9-7c2f8b5d1e36/cancel \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "atPeriodEnd": true }'

await upag.subscriptions.cancel('9a3c6e1f-0d58-4b72-a4e9-7c2f8b5d1e36', {
  atPeriodEnd: true,
});

Cancelar não reembolsa faturas já pagas. Detalhes em Cancelar assinatura. Para dar um período grátis antes da primeira cobrança, veja Teste grátis.

Primeiros passos

Fluxos

1. Criar produto e preço recorrente

2. Criar o cliente

3. Criar a assinatura

Pix

Cartão

4. Acompanhar por webhook

Renovações

Mudar itens

Cancelar

​1. Criar produto e preço recorrente

​2. Criar o cliente

​3. Criar a assinatura

​Pix

​Cartão

​4. Acompanhar por webhook

​Renovações

​Mudar itens

​Cancelar

1. Criar produto e preço recorrente

2. Criar o cliente

3. Criar a assinatura

Pix

Cartão

4. Acompanhar por webhook

Renovações

Mudar itens

Cancelar