Skip to Content
CheckoutOverview

Checkout — Overview

The hosted checkout is the page where the buyer actually sends funds. You don’t render the asset picker, deposit address, or QR yourself — the SDK opens our page (at https://checkout.infraio.xyz/<session_key>) and we handle the UI.

Three modes

Centered overlay popup, ~560×780 default. Storefront stays put. onSuccess fires when the popup closes after payment. Default mode.

Popup

Hard navigation to checkout. Best for popup-blocked browsers or mobile web where overlays feel jarring. Buyer returns via your success_url / cancel_url from the session.

Redirect

iframe inside your page. Best when you control layout end-to-end and want zero context switch. Auto-resizes via postMessage.

Embed

Pick-a-mode heuristic

If…Use
Desktop web, default e-commercePopup
Mobile webRedirect (popups + mobile = sad)
Strict CSP-locked admin panelRedirect
In-app webview / native checkout-in-a-pageEmbed
You want a fully custom buyer flow with white-label headerEmbed + hideHeader + your own wallet connect

What the buyer sees

Regardless of mode, the page surfaces:

  1. Order summary (line items, total, currency). Hide with hideSummary if you’ve already shown this on your side.
  2. Asset picker — list of chain × asset combinations you’ve enabled in merchant settings. Buyer picks one.
  3. Deposit address + QR + amount for the chosen combo. The buyer either scans, connects a wallet (WalletConnect button), or pays from a pre-connected wallet you supplied via the SDK.
  4. Status pulse — “Waiting for transfer”, “Tx detected (3/12 confirmations)”, “Paid”.
  5. Cancel button (always present) → triggers onCancel.

Customising the page

KnobHowLimits
Hide order summaryhideSummary: true on SDKBuyer can still see total in deposit panel
Hide InfraIO headerhideHeader: true on SDKPair with walletAddress for full white-label
Pre-connect a walletwalletAddress + walletChainId + onSignRequestBypasses the WalletConnect modal
Localelocale on SDK — one of en, vi, ja, ko, es, pt-BR, ru, tr, zh-CN, zh-TWLocalises the checkout and refund pages (and the wallet-connect modal). Unknown or omitted → falls back to en
Logo, brand colorMerchant dashboard → BrandingApplies globally, not per-session

Return URL behavior

For redirect mode the buyer always returns to one of:

  • success_url from the session (on settled payment)
  • cancel_url from the session (on cancel/abandon)
  • If you didn’t set those, the SDK falls back to the page that opened the checkout, with ?session_id=…&status=success|cancel appended

For popup and embed modes there’s no navigation — control returns to your page via onSuccess / onCancel. Use those to decide what UI to show next.

CSP and embedding

If you use embed mode, your CSP must allow our origin in frame-src:

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

The iframe carries the permissions policy allow="payment; clipboard-write" — it can invoke the Payment Request API and write to the clipboard, nothing more. It is not HTML-sandboxed: the checkout page is a full wallet-connecting app whose postMessage security (origin checks on both sides) and third-party wallet SDKs (WalletConnect, Coinbase, MetaMask) require a real same-origin scripting context, so an HTML sandbox attribute would break wallet connect for negligible isolation gain. Isolation comes instead from the cross-origin boundary, strict postMessage origin checks, and your frame-src CSP.

Mobile considerations

Popups are blocked aggressively on mobile Safari. If your traffic is mostly mobile, default to mode: "redirect". The popup overlay also covers the keyboard area on small screens — fine for amount entry, awkward for asset picking.

Branding (for the white-label crowd)

Full white-label requires:

  1. hideHeader: true on the SDK
  2. walletAddress pre-connected (buyer sees no WalletConnect)
  3. Your logo + brand color set in merchant dashboard branding
  4. (Optional) Custom domain for the checkout page — pay.your-shop.com instead of checkout.infraio.xyz. Self-serve via dashboard once your CNAME is verified.

What’s next

Chains & assetsOverview