Checkout — Resumen

El checkout alojado es la página donde el comprador efectivamente envía fondos. No renderizas el selector de activos, la dirección de depósito o el QR tú mismo: el SDK abre nuestra página (en https://checkout.infraio.xyz/<session_key>) y nosotros gestionamos la UI.

Tres modos

Popup superpuesto centrado, ~560×780 por defecto. La tienda se queda en su sitio. onSuccess se dispara cuando el popup se cierra tras el pago. Modo por defecto.

Popup

Navegación dura al checkout. Mejor para navegadores con popups bloqueados o web móvil donde los overlays se sienten chocantes. El comprador regresa vía tu success_url / cancel_url de la sesión.

Redirect

iframe dentro de tu página. Mejor cuando controlas el layout de principio a fin y quieres cero cambio de contexto. Se autodimensiona vía postMessage.

Embed

Heurística para elegir modo

Si…	Usa
Web de escritorio, e-commerce por defecto	Popup
Web móvil	Redirect (los popups suelen bloquearse en móvil)
Panel admin con CSP estrictamente bloqueado	Redirect
Webview in-app / checkout nativo en una página	Embed
Quieres un flujo de comprador totalmente personalizado con header white-label	Embed + `hideHeader` + tu propia conexión de wallet

Lo que ve el comprador

Independientemente del modo, la página muestra:

Resumen de la orden (line items, total, moneda). Ocúltalo con hideSummary si ya lo has mostrado en tu lado.
Selector de activos: lista de combinaciones cadena × activo que has habilitado en la configuración del comerciante. El comprador elige una.
Dirección de depósito por pedido (CREATE2) + QR + importe para la combinación elegida. El comprador escanea, conecta una wallet (botón WalletConnect), o paga desde una wallet preconectada que proporcionaste vía SDK. En TRON, Solana y TON el comprador paga directamente a tu wallet; ver Redes de pago directo a la wallet.
Pulso de estado: “Esperando transferencia”, “Tx detectada (3/12 confirmaciones)”, “Pagado”.
Botón Cancelar (siempre presente) → dispara onCancel.

Personalización de la página

Knob	Cómo	Límites
Ocultar resumen de orden	`hideSummary: true` en el SDK	El comprador aún puede ver el total en el panel de depósito
Ocultar header de InfraIO Pay	`hideHeader: true` en el SDK	Combina con `walletAddress` para white-label total
Pre-conectar una wallet	`walletAddress` + `walletChainId` + `onSignRequest`	Salta el modal de WalletConnect
Configuración regional	`locale` en el SDK — uno de `en`, `vi`, `ja`, `ko`, `es`, `pt-BR`, `ru`, `tr`, `zh-CN`, `zh-TW`	Localiza la página de checkout y las páginas de reembolso (y el modal de conexión de wallet). Desconocido u omitido → recurre a `en`
Logo, color de marca	Dashboard del comerciante → Branding	Se aplica globalmente, no por sesión

Comportamiento de URL de retorno

Para el modo redirect el comprador siempre regresa a uno de:

success_url de la sesión (en pago liquidado)
cancel_url de la sesión (en cancelar/abandonar)
Si no los configuraste, el SDK cae a la página que abrió el checkout, con ?session_id=…&status=success|cancel añadido

Para los modos popup y embed no hay navegación: el control vuelve a tu página vía onSuccess / onCancel. Úsalos para decidir qué UI mostrar después.

CSP e incrustación

Si usas el modo embed, tu CSP debe permitir nuestro origin en frame-src:


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

El iframe lleva la política de permisos allow="payment; clipboard-write": puede invocar la Payment Request API y escribir en el portapapeles, nada más. No añadas un atributo sandbox de HTML al iframe, porque rompe la conexión de wallet. El iframe se aísla mediante el límite cross-origin y tu CSP de frame-src.

Consideraciones móviles

Los navegadores móviles, sobre todo Safari, suelen bloquear los popups. Si la mayor parte de tu tráfico es móvil, usa mode: "redirect". En pantallas pequeñas el overlay del popup también cubre el área del teclado, lo que hace incómodo elegir un activo.

Branding white-label

White-label completo requiere:

hideHeader: true en el SDK
walletAddress preconectada (el comprador no ve WalletConnect)
Tu logo + color de marca configurados en el branding del dashboard del comerciante
(Opcional) Dominio personalizado para la página de checkout: pay.your-shop.com en lugar de checkout.infraio.xyz. Configúralo en el dashboard una vez que tu CNAME esté verificado.

Qué sigue

SDK → JavaScript: referencia completa de opciones por modo.
Conceptos → Sesiones: qué pasa en el lado del servidor mientras el comprador está en la página.
Conceptos → Cadenas y activos: qué combinaciones cadena×activo están disponibles en el selector.