<!-- Source: https://docs.infraio.xyz/pt-BR/checkout/overview -->
<!-- Last updated: 2026-10-04 -->

# 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](https://docs.infraio.xyz/pt-BR/sdks/javascript#popup) — 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.
- [Redirect](https://docs.infraio.xyz/pt-BR/sdks/javascript#redirect) — 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.
- [Embed](https://docs.infraio.xyz/pt-BR/sdks/javascript#embed) — 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.

## 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:

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. Em TRON, Solana e TON o comprador paga diretamente a sua carteira; veja [Redes com pagamento direto na carteira](https://docs.infraio.xyz/pt-BR/concepts/chains#redes-com-pagamento-direto-na-carteira).
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 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`:

```http
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:

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`. Configure
   no dashboard uma vez que o seu CNAME esteja verificado.

## Próximos passos

- [SDK → JavaScript](https://docs.infraio.xyz/pt-BR/sdks/javascript) — referência completa
  de opções por modo.
- [Conceitos → Sessões](https://docs.infraio.xyz/pt-BR/concepts/sessions) — o que acontece
  do lado do servidor enquanto o comprador está na página.
- [Conceitos → Redes e ativos](https://docs.infraio.xyz/pt-BR/concepts/chains) — quais
  combinações rede × ativo estão disponíveis no seletor.