Skip to Content
CheckoutOverview
View as Markdown

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 are often blocked on mobile)
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. On TRON, Solana and TON the buyer pays your wallet directly instead; see Direct-to-wallet networks.
  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 Pay 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. Don’t add an HTML sandbox attribute to the iframe, because it breaks wallet connection. The iframe is isolated by the cross-origin boundary and your frame-src CSP.

Mobile considerations

Mobile browsers, especially Safari, often block popups. If most of your traffic is mobile, use mode: "redirect". On small screens the popup overlay also covers the keyboard area, which makes picking an asset awkward.

White-label branding

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. Set it up in the dashboard once your CNAME is verified.

What’s next

Prepaid creditOverview