Skip to Content
CheckoutVisão geral

Checkout — Visão geral

O checkout hospedado é a página onde o comprador efetivamente envia os fundos. Você não renderiza o seletor de ativo, o endereço de depósito ou o QR por conta própria — o SDK abre a nossa página (em https://checkout.infraio.xyz/<session_key>) e a gente cuida da UI.

Três modos

Popup sobreposto centralizado, ~560×780 por padrão. A sua loja fica parada. onSuccess dispara quando o popup fecha após o pagamento. Modo padrão.

Popup

Navegação completa para o checkout. Melhor para navegadores que bloqueiam popup ou para mobile web onde overlays ficam desconfortáveis. O comprador retorna pela success_url / cancel_url da sessão.

Redirect

iframe dentro da sua página. Melhor quando você controla o layout de ponta a ponta e quer zero troca de contexto. Auto-redimensiona via postMessage.

Embed

Heurística para escolher o modo

Se…Use
Desktop web, e-commerce padrãoPopup
Mobile webRedirect (popups + mobile = tristeza)
Painel administrativo com CSP estritaRedirect
Webview in-app / checkout-numa-página nativoEmbed
Você quer um fluxo de comprador totalmente customizado com header white-labelEmbed + hideHeader + a sua própria conexão de carteira

O que o comprador vê

Independente do modo, a página mostra:

  1. Resumo do pedido (itens, total, moeda). Esconda com hideSummary se você já mostrou isso do seu lado.
  2. Seletor de ativo — lista de combinações rede × ativo que você habilitou nas configurações do lojista. O comprador escolhe uma.
  3. Endereço de depósito + QR + valor para a combinação escolhida. O comprador escaneia, conecta uma carteira (botão WalletConnect) ou paga a partir de uma carteira pré-conectada que você forneceu via SDK.
  4. Pulso de status — “Aguardando transferência”, “Tx detectada (3/12 confirmações)”, “Pago”.
  5. Botão Cancelar (sempre presente) → aciona onCancel.

Customizando a página

Botão de ajusteComoLimites
Esconder resumo do pedidohideSummary: true no SDKO comprador ainda vê o total no painel de depósito
Esconder header InfraIOhideHeader: true no SDKCombine com walletAddress para white-label completo
Pré-conectar uma carteirawalletAddress + walletChainId + onSignRequestPula o modal de WalletConnect
Idioma (locale)locale no SDK — um de en, vi, ja, ko, es, pt-BR, ru, tr, zh-CN, zh-TWLocaliza a página de checkout e as páginas de reembolso (e o modal de conexão de carteira). Desconhecido ou omitido → volta para en
Logo, cor da marcaDashboard do lojista → BrandingAplica globalmente, não por sessão

Comportamento da URL de retorno

Para o modo redirect o comprador sempre volta para um destes:

  • success_url da sessão (em pagamento liquidado)
  • cancel_url da sessão (em cancelamento/abandono)
  • Se você não configurou essas, o SDK faz fallback para a página que abriu o checkout, com ?session_id=…&status=success|cancel anexado

Para os modos popup e embed não há navegação — o controle retorna para a sua página via onSuccess / onCancel. Use isso para decidir qual UI mostrar em seguida.

CSP e embed

Se você usa o modo embed, o seu CSP precisa permitir a nossa origem em frame-src:

Content-Security-Policy:
  frame-src https://checkout.infraio.xyz https://checkout-dev.infraio.xyz;

O iframe carrega a política de permissões allow="payment; clipboard-write" — ele pode invocar a Payment Request API e escrever no clipboard, nada além disso. Ele não é HTML-sandboxeado: a página de checkout é um app completo de conexão de carteira cuja segurança de postMessage (checagens de origem dos dois lados) e SDKs de carteira de terceiros (WalletConnect, Coinbase, MetaMask) exigem um contexto de scripting real de mesma origem, então um atributo HTML sandbox quebraria a conexão de carteira por um ganho de isolamento insignificante. O isolamento vem, em vez disso, da fronteira cross-origin, das checagens estritas de origem do postMessage e do seu CSP de frame-src.

Considerações para mobile

Popups são bloqueados agressivamente no Safari mobile. Se o seu tráfego é principalmente mobile, use por padrão mode: "redirect". O overlay do popup também cobre a área do teclado em telas pequenas — ok para digitação de valor, desconfortável para escolha de ativo.

Branding (para o pessoal de white-label)

White-label completo requer:

  1. hideHeader: true no SDK
  2. walletAddress pré-conectado (o comprador não vê WalletConnect)
  3. O logo + cor da marca configurados no branding do dashboard do lojista
  4. (Opcional) Domínio customizado para a página de checkout — pay.your-shop.com no lugar de checkout.infraio.xyz. Self-service via dashboard uma vez que o seu CNAME esteja verificado.

Próximos passos

Redes e ativosVisão geral