LYNX UPBANK · Tecnologia de pagamentos Pix & Crypto

Criar cobrança de uso único

POST/v1/billing/single-use/create

Cria uma cobrança com URL exclusiva que aceita UM único pagamento. Nasce PENDING; ao confirmar o primeiro PIX vira PAID e a página passa a exibir 'Esta cobrança já foi paga.' (sem QR Code). Se o prazo terminar sem pagamento, vira EXPIRED. O bloqueio do segundo pagamento é atômico no servidor.

Permissão necessária: BILLING:CREATE

Parâmetros

Parâmetro	Tipo	Descrição
`title`obrig.	string	Título da cobrança (ex.: Renovação do plano).
`amountCents`obrig.	integer	Valor em centavos. Mínimo 200 (R$ 2,00). Respeita o limite por transação da conta.
`description`	string	Descrição exibida na página.
`externalReference`	string	Sua referência (ex.: fatura_123456). Volta no check e no webhook billing.paid para conciliação.
`expiresIn`	integer	Segundos até expirar (padrão 2592000 = 30 dias; mín. 300, máx. 90 dias).
`passFee`	boolean	Se true, repassa a taxa ao pagador.
`customer`	object	Dados do cliente { name, email, cellphone, taxId } (opcional, informativo).
`metadata`	object	Chave/valor livre, devolvido no check e no webhook.
`layout`	string	"simple" (padrão, link de cobrança enxuto) ou "full" (página de venda completa).
`collectFields`	object	Quais dados pedir no checkout: { "name", "email", "whatsapp", "cpf": bool }. Padrão do uso único: nenhum (anônimo).
`…personalização`	mixed	Aceita TODOS os campos de personalização do Criar checkout: ctaText, accentColor, imageUrl, logoUrl, merchantDisplayName, gallery, videoUrl, benefits, badges, guarantee, testimonials, faq, scarcity, orderBump, delivery, supportWhatsapp. Veja a tabela completa em Criar checkout.
`Idempotency-Key`	header	Ex.: fatura_123456. Reenvios com a mesma chave devolvem o checkout JÁ criado (nunca duplica a cobrança).

Boas práticas

Cada chamada (sem Idempotency-Key repetida) gera uma cobrança e uma URL novas, nunca reutilize o link para outra fatura.
Envie Idempotency-Key com o ID da sua fatura: retries por timeout retornam o MESMO checkout em vez de criar um segundo link.
Concilie pelo webhook billing.paid usando externalReference, ele vem com singleUse: true, netAmount, paidAt, payer e endToEndId.
Depois de PAID a URL continua acessível, mas sem QR Code/copia e cola, o segundo pagamento é bloqueado de forma atômica no servidor.
Sem código: no painel (Vendas), os 3 modelos, Link rápido, Link de cobrança e Página de venda, têm a opção 'Uso único' com validade configurável (1h a 90 dias), usando exatamente a mesma máquina de estados e o mesmo bloqueio atômico desta API.
Rastreio: links de uso único também aceitam parâmetros ocultos na URL (?cliente=...&pedido=...), veja 'Parâmetros ocultos'.

Requisição

bash

curl -X POST https://lynxpix.cc/api/v1/billing/single-use/create \
  -H "Authorization: Bearer lynx_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"title":"Renovação do plano","amountCents":5000,"description":"Renovação mensal do cliente","externalReference":"fatura_123456","expiresIn":2592000,"passFee":false,"collectFields":{"name":true,"email":false,"whatsapp":false,"cpf":true},"accentColor":"#14B2EC","customer":{"name":"João Silva","email":"joao@email.com","cellphone":"11999998888","taxId":"12345678900"},"metadata":{"clienteId":"123","usuario":"cliente123","referenciaGestor":"ABC123"}}'

Resposta

json

{
  "data": {
    "id": "chk_single_1a2b3c",
    "url": "https://lynx.app/pay/fatura-123456-9f8a2c",
    "status": "PENDING",
    "singleUse": true,
    "amount": 5000,
    "externalReference": "fatura_123456",
    "expiresAt": "2026-08-21T15:00:00Z",
    "createdAt": "2026-07-22T15:00:00Z"
  },
  "error": null
}