Catálogo e Assinaturas

Você tem dois caminhos pra receber pagamentos online — escolha o que faz sentido:

                          ┌─────────────────────────────────────┐
                          │  CHECKOUT VIA OFFER                  │
                          │  (catálogo: one-time ou recorrente)  │
                          └─────────────────────────────────────┘
       Product                  Catálogo
          │                     (você cria)
          ▼
        Offer                   Preço + ciclo + slug
          │                     (você cria, URL /o/seu-user/:slug)
          ▼
     ──── cliente clica e paga ────
          │
          ▼
    ┌─────┴────────────────┐
    │                      │
 Customer            Invoice + Transaction       (recurring)
    │             ou somente Transaction          (one-time)
    └──────────────────┬───┘
                       ▼
                webhooks cashin.*
                       ▼
                seu sistema processa


                          ┌─────────────────────────────────────┐
                          │  LINK DE PAGAMENTO RÁPIDO            │
                          │  (sem produto, só amount + URL)      │
                          └─────────────────────────────────────┘
     QuickLink            Valor próprio + slug
          │               (você cria, URL /p/seu-user/:slug)
          ▼
     ──── cliente paga ────
          │
          ▼
       Transaction        (sem Customer, sem Invoice)
          │
          ▼
     webhook cashin.paid

O que você cria vs o que é criado automaticamente:

Quando usar cada um:

• Offer one-time (billingCycle: null) — venda única num catálogo (e-book, curso, ticket de evento). Cliente acessa /o/seu-user/ebook-receitas. Entrega de PDF: se a Offer avulsa tiver um deliveryPdfUrl (upload via POST /offers/:id/delivery-pdf), o cliente recebe o arquivo automaticamente no e-mail de pagamento confirmado — anexado e com botão de download. Vale só pra Offers avulsas; assinaturas não entregam PDF.
• Offer recurring (billingCycle: "MONTHLY") — assinatura/SaaS com renovação automática. Aceita cupons.
• QuickLink — cobrança avulsa sem produto formalizado. Não aceita cupom. Não cria Invoice. Útil pra doação, cobrança ad-hoc, etc.
• Subscription standalone — você define amount + ciclo direto pra um Customer existente (sem passar por Offer). B2B: contador cobrando honorários, advogado cobrando avença.
• Invoice avulsa — fatura única direcionada a um Customer (consulta, projeto). Equivale a "Cobrar de cliente uma vez".

Detalhes profundos: Produtos e Ofertas · Links rápidos.

Cenário: você quer vender o "Plano Pro" a R$ 49/mês.

1. Crie o Product:

curl -X POST "https://api.pagnovo.com/v2/products" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Pro",
    "description": "Acesso completo a todas as features"
  }'
# → { "id": "prd_abc...", ... }

2. Crie uma Offer recurring vinculada a esse Product:

curl -X POST "https://api.pagnovo.com/v2/offers" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prd_abc...",
    "name": "Mensal",
    "slug": "plano-pro-mensal",
    "amount": 4900,
    "billingCycle": "MONTHLY"
  }'
# → { "id": "off_xyz...", "slug": "plano-pro-mensal", ... }

amount: 4900 = R$ 49,00. Valores em centavos. billingCycle: "MONTHLY" torna a Offer recorrente. slug é obrigatório (V2) — vira a parte final da URL pública. Use [a-z0-9-], único por conta.

3. A URL pública do checkout já está pronta:

A Offer ganha automaticamente uma URL no formato https://pay.pagnovo.com/o/seu-slug-de-conta/plano-pro-mensal — é o que você compartilha. Não precisa criar nenhum link adicional.

4. Cliente clica, paga, e o restante acontece sozinho:

• Cadastro de Customer é criado automaticamente.
• Primeira Invoice gerada e marcada como PAID.
• Subscription criada com status ACTIVE.
• Você recebe webhook cashin.paid.
• Mês seguinte: nova Invoice é gerada e cobrada automaticamente.

Alternativa rápida (sem produto): se você quer só uma URL pra receber um valor avulso (sem cadastrar Product/Offer), use QuickLink:

curl -X POST "https://api.pagnovo.com/v2/quick-links" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Doação Natal",
    "slug": "doacao-natal",
    "amount": 5000
  }'
# → URL pública: https://pay.pagnovo.com/p/seu-slug-de-conta/doacao-natal

Detalhes adicionais: Criar produto, Criar oferta, Links rápidos, Cupons.

Depois do setup básico, você vai querer entender com mais profundidade três recursos que dão poder real ao seu fluxo recorrente:

• Links de pagamento (visão geral) — opções avançadas: janela de validade (validFrom/validUntil), limite de usos (maxUses), duplicar um link pra rodar campanha sem mexer no original. QuickLink sempre gera Transaction direta (sem Customer/Invoice), valor próprio definido na criação.
• Subscriptions (visão geral) — como funciona o ciclo de cobrança (nextBillingAt, daysBeforeDueToBill), o snapshot pattern (mudanças só afetam o próximo ciclo), pause vs cancel, retry de cobranças vencidas, multa e juros automáticos.
• Invoices (visão geral) — estrutura de fatura individual (items que somam com amount), regras estritas de edição (só DRAFT/PENDING sem attempt APPROVED), multas e juros, estornos parciais, reenvio manual de notificação.

Esses são os blocos que fazem o motor de assinatura funcionar — vale a leitura quando você for pra produção.

Black Friday — cupom de 15% off

curl -X POST "https://api.pagnovo.com/v2/coupons" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BLACKFRIDAY",
    "discountType": "PERCENTAGE",
    "discountValue": 1500,
    "validUntil": "2026-11-30T23:59:59.000Z",
    "offerIds": ["off_plano_pro_mensal"]
  }'

discountValue: 1500 = 15% (basis points, onde 10.000 = 100%). Para um cupom de R$ 10 fixo, troque discountType por FIXED e mande discountValue: 1000 (R$ 10 em centavos).

Detalhes: Cupons (visão geral), Criar cupom.

Mudança de preço — sem afetar assinantes existentes

Editar amount de uma Offer com assinantes ativos não muda o que eles pagam (o valor é congelado no momento da assinatura), mas a API bloqueia a edição pra evitar confusão. O padrão correto:

1. Crie uma Offer nova com o preço novo.
2. Marque a antiga como active: false (some das listagens de venda; assinaturas existentes continuam funcionando).
3. Aponte seus PaymentLinks pra Offer nova.

Nunca edite uma Offer com assinantes ativos esperando que o preço mude pra eles. Veja a explicação detalhada em Produtos e Ofertas.

Histórico do cliente — view 360°

Quando precisar entender tudo que aconteceu com um cliente (suporte, dunning, churn):

curl -X GET "https://api.pagnovo.com/v2/customers/{id}/history" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

Retorna assinaturas, invoices, pagamentos e refunds com LTV, ticket médio e total em aberto — tudo em centavos. Veja Histórico do cliente.

Pra SaaS, três a quatro tipos de evento cobrem 95% dos casos. Use Payload v2 (recomendado para integrações novas):

💡 Boas práticas: valide assinatura HMAC (detalhes), retorne 200 só depois da assinatura passar, processe de forma assíncrona (enfileire e responda 200 já), guarde o x-trace-id junto com sua linha. Faça o handler idempotente — reentregas são esperadas.

Detalhes: Webhooks (visão geral), Payload v2, Verificação de assinatura.

Mesmo se sua principal venda for recorrente, alguns casos exigem cobrança avulsa:

Cliente B2B querendo NF e pagamento à vista anual:

Crie uma Offer one-time (sem billingCycle) com o valor cheio:

{
  "productId": "prd_abc...",
  "name": "Plano Pro Anual à vista",
  "amount": 49000
}

Cliente paga uma vez e o acesso é liberado. Sem recorrência.

Cobrança avulsa fora do checkout (ex: upgrade, taxa de setup, multa):

Você pode gerar uma Invoice direta para um Customer existente (sem passar por PaymentLink) usando POST /v2/invoices — veja Criar Invoice. Útil pra upgrades manuais, taxas pontuais e cobranças B2B fora do checkout.

Mistura — assinatura recorrente + cobranças avulsas:

Pra cada produto ou variação, crie uma Offer separada. Assinaturas vêm das Offers recurring; faturas avulsas vêm das Offers one-time. Tudo aponta pro mesmo Product (e portanto pro mesmo histórico de cliente), então o relatório consolidado continua coerente.