Documentação

Links de pagamento (visão geral)

Um QuickLink é uma URL pública (https://pay.pagnovo.com/p/seu-slug-de-conta/<slug>) pra cobrança rápida via PIX. Tem amount próprio, NÃO depende de Product/Offer. Cliente acessa, paga, e gera Transaction direto — sem Customer, sem Invoice.

você cria QuickLink → cliente acessa pay.pagnovo.com/p/seu-user/doacao
                     ↓
                preenche dados + paga
                     ↓
              Transaction (sem Customer, sem Invoice)
                     ↓
            webhook cashin.paid no seu sistema

Multi-uso: o mesmo QuickLink pode receber N pagamentos de pessoas diferentes — limitado opcionalmente por maxUses.

V2: o que antes era chamado de "Payment Link" foi renomeado pra QuickLink e simplificado: agora tem amount próprio (em vez de apontar pra Offer). Pra catálogo de produtos com checkout, use Offers.

QuickLink vs Checkout via Offer vs Invoice avulsa

Três fluxos diferentes pra cobrar — escolha o que faz sentido:

Quando você usa...	Use QuickLink	Use Offer (Checkout)	Use Invoice avulsa (POST /v2/invoices)
Cobrança avulsa simples (doação, mensalidade fixa)	✓	—	—
Vende um produto/serviço de catálogo (e-book, curso)	—	✓ (one-time)	—
Assinatura recorrente	—	✓ (recurring)	—
Cobrança direcionada a cliente específico, valor único	—	—	✓
Cliente B2B que pede NF	—	—	✓
Aceita cupom de desconto	✗	✓ (recurring apenas)	✗
Cria Customer no banco	✗	✓ (recurring)	✓
Cria Invoice	✗	✓ (recurring)	✓

Em uma frase: QuickLink é o jeito mais rápido de receber um valor. Offer é catálogo. Invoice avulsa é boleto pontual direcionado.

Campos principais

name (obrigatório) — nome interno do link. NÃO é exibido ao cliente final, só nas suas listagens.

slug (obrigatório) — parte final da URL pública (pay.pagnovo.com/p/seu-slug-de-conta/<slug>). 3–60 caracteres, apenas a-z, 0-9 e hífen. Único por conta.

amount (obrigatório) — valor da cobrança em centavos. Mínimo R$ 1,00 (100), máximo R$ 50.000,00 (5000000).

description — texto exibido ao pagador no checkout. Opcional. Max 500 chars.

validFrom / validUntil — janela de tempo em que o link aceita pagamentos. validUntil não pode ser passado. Se omitidos, o link é válido sem janela.

maxUses — limite global de pagamentos que esse link aceita. null = ilimitado. Quando currentUses == maxUses, o link rejeita novos pagamentos.

metadata — JSON arbitrário pra anexar dados do seu sistema (UTM, campanha, etc). Max 8KB.

Estados do QuickLink

Status	O que significa	Aceita novos pagamentos?
`ACTIVE`	Tudo OK, dentro da janela `validFrom`/`validUntil` e abaixo do `maxUses`.	✓
`PAUSED`	Você pausou manualmente via /pause. Histórico fica preservado.	✗
`ARCHIVED`	Você arquivou via DELETE. Some das listagens (a menos que `includeDeleted=true`). Não aceita edição. Transações já confirmadas continuam intactas.	✗

Diferente da versão anterior, QuickLink não tem status EXPIRED automático. Quando validUntil passa, novos pagamentos são rejeitados via validação no momento do checkout, mas o status do link continua ACTIVE no banco. Atualize validUntil ou pause o link explicitamente se quiser parar.

Pausar vs arquivar:

Pausar é temporário. Use quando vai voltar a aceitar (ex: campanha sazonal fora do ar). Pode reativar via /resume.
Arquivar é final. Use quando o link nunca mais será usado. Não há restore via API.

Fluxo de uso

1. Você cria o link:

bash

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 de Natal",
    "slug": "doacao-natal",
    "amount": 5000
  }'
# → { "id": "ql_abc...", "slug": "doacao-natal", ... }

2. Compartilha a URL https://pay.pagnovo.com/p/seu-slug-de-conta/doacao-natal com seus clientes.

3. Cliente acessa, preenche dados (nome, e-mail, documento, telefone) e paga via PIX.

4. A Pagnovo cria automaticamente uma Transaction com:

sourceType: "QUICK_LINK"
quickLinkId apontando pro seu link
Dados do pagador nos campos payerFullName, payerDocument, payerEmail
Sem Customer, sem Invoice (esse é o ponto)

5. Você recebe webhook cashin.paid com transaction_id e quick_link_id.

6. Pra acompanhar performance, use /v2/quick-links/:id (retorna stats.transactionsGenerated, transactionsPaid, totalRevenue em centavos) ou /v2/quick-links/:id/transactions (lista paginada).

Detalhes adicionais: Criar link, Duplicar link.