Referência da API

Criar link de pagamento

Cria um QuickLink: cobrança rápida via PIX com URL pública (`pay.${BRAND.domain}/p/seu-slug-de-conta/:slug`). Tem **amount próprio**, NÃO depende de Product/Offer. Quando alguém paga, gera Transaction direta — sem Customer, sem Invoice. Multi-uso: 1 link → N transações de pessoas diferentes. A chave de API precisa da permissão `isInvoiceAvailable`.

POST/v2/quick-links

QuickLink ≠ Checkout via Offer

amount Use QuickLink pra cobrança avulsa one-time (doação, mensalidade, consulta). Pra catálogo com produto/ofertas recorrentes, use **POST /v2/offers**. Pra cobrar cliente específico, use **POST /v2/invoices** (avulsa) ou **POST /v2/subscriptions** (standalone).

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

namestringobrigatório

Nome interno do link (NÃO é exibido ao cliente final). Mostrado nas suas listagens e relatórios.

Exemplo: Doação de Natal

slugstringobrigatório

Parte final da URL pública (`pay.${BRAND.domain}/p/seu-slug-de-conta/<slug>`). 3-60 caracteres, apenas `a-z`, `0-9` e hífen. Único por conta.

Exemplo: doacao-natal

amountnumber (centavos)obrigatório

Valor da cobrança em centavos. Mínimo R$ 1,00 (`100`). Máximo R$ 50.000,00 (`5000000`).

Exemplo: 5000

descriptionstring | nullopcional

Texto exibido ao pagador no checkout. Opcional. Max 500 chars.

Exemplo: Sua contribuição pro projeto

validFromstring (ISO 8601)opcional

Data a partir da qual o link aceita pagamentos. Pode estar no passado.

Exemplo: 2026-12-01T00:00:00.000Z

validUntilstring (ISO 8601)opcional

Data de expiração do link. **Não pode estar no passado** — o servidor rejeita com 400. Se omitido, o link nunca expira.

Exemplo: 2026-12-31T23:59:59.000Z

maxUsesnumber | nullopcional

Limite global de pagamentos aceitos. `null` ou ausente = ilimitado. Máximo: 1.000.000.

Exemplo: 1000

metadataobjectopcional

JSON arbitrário pra anexar dados do seu sistema. Max 8KB.

Exemplo: { "campaign": "natal-2026" }

Body da requisição

Content-Type: application/json

JSON

{
  "name": "Doação de Natal",
  "slug": "doacao-natal",
  "description": "Sua contribuição pro projeto",
  "amount": 5000,
  "validFrom": "2026-12-01T00:00:00.000Z",
  "validUntil": "2026-12-31T23:59:59.000Z",
  "maxUses": 1000,
  "metadata": { "campaign": "natal-2026" }
}

Respostas

201

QuickLink criado. amount e totalRevenue em centavos.

JSON

{
  "id": "ql_a8f3d2e1-9b4c-4e5f-8a7d-2e5f6c1d4b9a",
  "createdByUserId": "u-1234",
  "name": "Doação de Natal",
  "slug": "doacao-natal",
  "description": "Sua contribuição pro projeto",
  "amount": 5000,
  "status": "ACTIVE",
  "validFrom": "2026-12-01T00:00:00.000Z",
  "validUntil": "2026-12-31T23:59:59.000Z",
  "maxUses": 1000,
  "currentUses": 0,
  "transactionsGenerated": 0,
  "totalRevenue": 0,
  "metadata": { "campaign": "natal-2026" },
  "deletedAt": null,
  "createdAt": "2026-05-26T14:32:01.923Z",
  "updatedAt": "2026-05-26T14:32:01.923Z"
}

400

Validação falhou: slug em uso, slug com formato inválido, amount fora de range, validUntil no passado, ou campos legacy (offerId, daysToDue, billingCycle, etc) enviados.

JSON

{
  "status": 400,
  "error": "Slug \"doacao-natal\" ja esta em uso"
}

Exemplos

cURL

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
  }'

JavaScript

const token = Buffer.from("secret:" + process.env.PAGNOVO_SECRET_KEY).toString("base64");

const res = await fetch("https://api.pagnovo.com/v2/quick-links", {
  method: "POST",
  headers: { Authorization: `Basic ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Doação de Natal",
    slug: "doacao-natal",
    amount: 5000,
    maxUses: 1000,
  }),
});

const link = await res.json();
// URL pública é construída pelo seu sistema com o slug da sua conta:
// https://pay.pagnovo.com/p/SEU_USER_SLUG/<link.slug>
console.log("Slug:", link.slug);