Skip to Content
Links de pagamentoVisão geral

Links de pagamento — Visão geral

Um Link de pagamento é uma URL compartilhável que coloca um comprador num checkout hospedado que você já configurou. Sem SDK, sem integração de servidor — emita no dashboard, compartilhe e o mesmo webhook payment.settled dispara quando os fundos confirmarem on-chain.

Por baixo dos panos, um Link de pagamento é uma CheckoutSession — “Link de pagamento” é só o nome do lado do dashboard para uma sessão que não foi criada por um fluxo de SDK dirigido pelo comprador. Mesmo contrato de webhook, mesma liquidação on-chain, mesmas taxas.

Usos comuns:

  • Faturar um cliente avulso sem escrever código
  • Páginas de venda em que o time de dev não vai ligar um carrinho customizado neste trimestre
  • Follow-ups B2B — cole o link num e-mail e dê o caso por encerrado
  • Páginas de gorjeta de valor fixo no estilo “Buy me a coffee”

Crie um

Hoje isso é só pelo dashboard:

  1. Entre no dashboard do lojista 
  2. Payments → Payment Links → + New link
  3. Escolha um dos dois caminhos:
    • New order — informe itens, moeda, dados do cliente e metadata opcional. O dashboard cria o Order e o Link de pagamento numa única chamada.
    • Existing order — escolha um pedido PENDING (por exemplo, o comprador abandonou o link anterior). Re-emite um link novo apoiado pelo mesmo pedido, mantendo o histórico de pedido intacto.
  4. Salve → o dashboard mostra a URL https://checkout.infraio.xyz/cst_… com botão de copiar e download de QR code. Links em modo de teste usam checkout-dev.infraio.xyz para que o ambiente fique codificado no hostname.

Cada Link de pagamento é de uso único hoje: assim que um comprador paga, a sessão é COMPLETED. Se uma sessão expirar antes do pagamento (TTL padrão de 30 minutos), abra a página de detalhe do pedido e clique em Re-create link para emitir um novo contra o mesmo pedido.

O que o comprador vê

  1. Ele aterrissa em checkout.infraio.xyz/<session_key> — a mesma UI hospedada de checkout que você teria a partir de uma sessão emitida pelo SDK.
  2. Ele segue o fluxo padrão escolher-ativo → enviar fundos → esperar confirmação descrito em Checkout — Visão geral.
  3. payment.settled dispara no seu webhook com o pedido, o intent, o recibo, o tx hash on-chain e a contagem de confirmações — o mesmo payload de qualquer outro pagamento liquidado. Veja Webhooks para o schema.

O que o dashboard te dá

A superfície de Links de pagamento hoje vem com:

  • Visão de lista — todo link que você emitiu, com paginação por cursor, status, valor, número do pedido pai, cliente, expiração e uma abertura com um clique para a URL do comprador.
  • Filtros — status (ACTIVE / COMPLETED / EXPIRED / CANCELED), faixa de datas e busca em texto livre por número do pedido, nome do cliente, e-mail ou referência externa.
  • Exportação CSV — um clique, respeita os filtros atuais.
  • Faixa de KPIs — contagens por status, com escopo no ambiente atual (live vs test) via o header X-Environment para que os números sempre batam com o que a tabela está mostrando.
  • Página de detalhe — resumo do pedido, histórico de sessões (cada tentativa para este pedido), histórico on-chain com links para o block explorer e uma ação Re-create link para sessões que expiraram antes do pagamento.

Limitações hoje

  • Sem API programática — os links precisam ser criados no dashboard. O SDK pode criar sessões de uso único equivalentes via POST /b2b/v1/checkout-sessions/quick (veja Referência da API), mas a UX de “URL compartilhável de longa duração” é só no dashboard por enquanto.
  • Sem autenticação por comprador — qualquer um com a URL pode pagar. O modelo de uso único mitiga isso em parte; a vinculação total de identidade do comprador está no roadmap abaixo.
  • Branding é global — o link usa o logo do lojista, a cor da marca e o raio das bordas configurados em Settings → Branding. Overrides de branding por link ainda não foram expostos na UI do dashboard.

Roadmap

Itens que sabemos que queremos, priorizados do mais alto ao mais baixo:

  • Criação programática — um endpoint POST /b2b/v1/payment-links que espelhe o diálogo de duas abas do dashboard e retorne a mesma checkout_url. Combina naturalmente com listagem + revogação.
  • Expiração por tempo — o link fica válido até uma data específica, não só até o TTL da sessão expirar. Necessário para fluxos de faturamento em que “vencimento em 14 dias” é o prazo natural.
  • Links reutilizáveis — páginas multi-comprador estilo Stripe (doação, gorjeta, contas recorrentes). Hoje todo link é de uso único.
  • Identidade por comprador — travar um link a um e-mail ou carteira específicos para que não possa ser encaminhado.
  • Geração de QR pelo lado da API — o dashboard renderiza QR codes do lado do cliente hoje; expor isso na API para impressão de etiquetas e recibos embutidos está na lista.

Veja também

Visão geralJavaScript / Navegador