LYNX UPBANK · Tecnologia de pagamentos Pix & Crypto

Checkout de uso único

Um checkout de uso único é um link de pagamento que aceita UM único PIX e morre. Perfeito para fatura, pedido, mensalidade ou qualquer cobrança individual: depois do primeiro pagamento confirmado, a página passa a mostrar "Esta cobrança já foi paga." e qualquer nova tentativa é rejeitada pelo servidor.

Ciclo de vida

Parâmetro	Tipo	Descrição
`PENDING`	estado	Aguardando pagamento. A página gera 1 QR Code compartilhado, todos que abrirem o link veem a MESMA cobrança.
`PAID`	estado	Primeiro pagamento confirmado. O link é encerrado na hora; novas tentativas recebem HTTP 409.
`EXPIRED`	estado	A validade venceu sem pagamento. Estado definitivo (HTTP 410), crie outra cobrança.

Bloqueio atômico contra pagamento duplo

A transição PENDING → PAID acontece com lock atômico no banco: mesmo que duas pessoas abram o link ao mesmo tempo, existe um único QR ativo e só o primeiro PIX é aceito. Impossível receber duas vezes pela mesma cobrança.

Jeito 1, Pelo painel (sem código)

Os 3 modelos de página aceitam uso único ao criar, em Painel → Vendas:

Link rápido, ative o switch "Uso único" no formulário (validade fixa de 30 dias).
Link de cobrança, no passo Cobrança do assistente, ative "Uso único" e escolha a validade.
Página de venda, no passo Produto do assistente, ative "Uso único" e escolha a validade. Compatível com order bump, galeria, vídeo e todos os blocos.

Validade: 24 horas, 3 dias, 7 dias, 30 dias (padrão) ou 90 dias. Vencendo sem pagamento, o link expira sozinho.
Imutável: a opção não pode ser ligada/desligada depois de criada, isso protege o bloqueio atômico. Os demais campos (título, descrição, visual) continuam editáveis.
Acompanhamento: o card em Vendas mostra o estado em tempo real, Uso único (aguardando), Pago ✓ ou Expirado.
Repassar taxa: funciona normalmente, o pagador paga a taxa por cima e você recebe o valor cheio.

Jeito 2, Pela API

Para gerar cobranças de uso único programaticamente (ex.: uma por fatura do seu sistema), use POST /v1/billing/single-use/create com Idempotency-Key para retries seguros, e concilie pelo webhook billing.paid (vem com singleUse: true e o seu externalReference) ou por GET /v1/billing/single-use/check.

bash

curl -X POST https://SEU-DOMINIO/api/v1/billing/single-use/create \
  -H "Authorization: Bearer SUA_CHAVE" -H "Content-Type: application/json" \
  -H "Idempotency-Key: fatura_123456" \
  -d '{ "title": "Renovação do plano", "amountCents": 5000, "externalReference": "fatura_123456", "expiresIn": 2592000 }'

Referência completa: Uso único · criar e Uso único · consultar no menu Referência da API.

Rastreamento (parâmetros ocultos)

Links de uso único aceitam os mesmos parâmetros ocultos de rastreio dos checkouts normais, basta anexar à URL (ou usar o gerador de link com rastreamento, ícone de radar em Vendas):

text

https://lynx.app/pay/fatura-123456-9f8a2c?cliente=joao&pedido=A77&utm_source=whatsapp

Os parâmetros ficam invisíveis para o pagador, são gravados em metadata da transação e aparecem no painel (seção Rastreio), no extrato e no webhook. Veja regras e limites em Parâmetros ocultos.

Painel ou API, qual usar?

Parâmetro	Tipo	Descrição
`Painel`	quando usar	Cobranças avulsas do dia a dia: fatura pontual, pedido fechado no WhatsApp, venda única. Zero código.
`API`	quando usar	Volume/automação: seu sistema emite 1 link por fatura, com idempotência, externalReference e conciliação automática via webhook.

Mesmo motor por baixo

Painel e API usam exatamente a mesma máquina de estados e o mesmo bloqueio atômico, um link de uso único criado no painel se comporta de forma idêntica a um criado via API.