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ão	Popup
Mobile web	Redirect (popups costumam ser bloqueados no mobile)
Painel administrativo com CSP estrita	Redirect
Webview in-app / checkout-numa-página nativo	Embed
Você quer um fluxo de comprador totalmente customizado com header white-label	Embed + `hideHeader` + a sua própria conexão de carteira

O que o comprador vê

Independente do modo, a página mostra:

Resumo do pedido (itens, total, moeda). Esconda com hideSummary se você já mostrou isso do seu lado.
Seletor de ativo — lista de combinações rede × ativo que você habilitou nas configurações do lojista. O comprador escolhe uma.
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. Em TRON, Solana e TON o comprador paga diretamente a sua carteira; veja Redes com pagamento direto na carteira.
Pulso de status — “Aguardando transferência”, “Tx detectada (3/12 confirmações)”, “Pago”.
Botão Cancelar (sempre presente) → aciona onCancel.

Customizando a página

Botão de ajuste	Como	Limites
Esconder resumo do pedido	`hideSummary: true` no SDK	O comprador ainda vê o total no painel de depósito
Esconder header InfraIO Pay	`hideHeader: true` no SDK	Combine com `walletAddress` para white-label completo
Pré-conectar uma carteira	`walletAddress` + `walletChainId` + `onSignRequest`	Pula o modal de WalletConnect
Idioma (locale)	`locale` no SDK — um de `en`, `vi`, `ja`, `ko`, `es`, `pt-BR`, `ru`, `tr`, `zh-CN`, `zh-TW`	Localiza 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 marca	Dashboard do lojista → Branding	Aplica 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. Não adicione o atributo HTML sandbox ao iframe, porque ele quebra a conexão de carteira. O iframe é isolado pela fronteira cross-origin e pelo seu CSP de frame-src.

Considerações para mobile

Navegadores mobile, especialmente o Safari, costumam bloquear popups. Se a maior parte do seu tráfego é mobile, use mode: "redirect". Em telas pequenas, o overlay do popup também cobre a área do teclado, o que torna desconfortável a escolha de ativo.

Branding white-label

White-label completo requer:

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

Próximos passos

SDK → JavaScript — referência completa de opções por modo.
Conceitos → Sessões — o que acontece do lado do servidor enquanto o comprador está na página.
Conceitos → Redes e ativos — quais combinações rede × ativo estão disponíveis no seletor.