結帳 — 總覽
託管結帳頁是買家實際送出資金的頁面。你不需要自己渲染資產
選擇器、每筆訂單獨立收款位址(CREATE2)或 QR code — SDK 會開啟我們的頁面（位於
https://checkout.infraio.xyz/<session_key>），UI 由我們處理。
三種模式
置中的覆蓋式彈出視窗，預設約 560×780。商店頁面維持原狀。
付款完成、彈出視窗關閉時觸發 onSuccess。預設模式。
直接導向結帳頁。最適合彈出視窗被封鎖的瀏覽器，或是覆蓋層
體驗不佳的行動網頁。買家會透過 session 中的 success_url /
cancel_url 返回。
內嵌在你頁面中的 iframe。適合你想端到端控制版面、不想有 情境切換的場景。透過 postMessage 自動調整大小。
Embed選擇模式的判斷準則
| 情境… | 使用 |
|---|---|
| 桌面網頁，一般電商情境 | Popup |
| 行動網頁 | Redirect（行動裝置上 popup 常被封鎖） |
| 有嚴格 CSP 限制的後台系統 | Redirect |
| App 內 webview / 頁面內原生結帳 | Embed |
| 想要完全自訂、帶白牌 header 的買家流程 | Embed + hideHeader + 你自己的錢包連接 |
買家會看到什麼
無論哪種模式，頁面都會呈現：
- 訂單摘要（商品項目、總額、幣別）。若你已在自己那端顯示
過，可用
hideSummary隱藏。 - 資產選擇器 — 你在商家設定中啟用的鏈 × 資產組合清單。買家 從中挑一個。
- 所選組合的獨立收款位址 + QR code + 金額。買家可以掃描、連接 錢包（WalletConnect 按鈕），或直接用你透過 SDK 預先提供好的 已連接錢包付款。在 TRON、Solana 與 TON 上，買家直接付款到你的資金庫錢包；請見直達錢包的網路。
- 狀態脈動指示 — 「等待轉帳中」、「偵測到交易（3/12 確認）」、「已付款」。
- 取消按鈕（一律顯示）→ 觸發
onCancel。
自訂頁面
| 選項 | 做法 | 限制 |
|---|---|---|
| 隱藏訂單摘要 | SDK 上設定 hideSummary: true | 買家仍可在存款面板中看到總額 |
| 隱藏 InfraIO Pay header | SDK 上設定 hideHeader: true | 搭配 walletAddress 達成完整白牌 |
| 預先連接錢包 | walletAddress + walletChainId + onSignRequest | 略過 WalletConnect 彈窗 |
| 語系 | SDK 上的 locale — en、vi、ja、ko、es、pt-BR、ru、tr、zh-CN、zh-TW 之一 | 同時本地化結帳頁與退款頁（以及錢包連接彈窗）。未知或省略 → 回退到 en |
| Logo、品牌色 | 商家儀表板 → Branding | 全域套用，不是依 session 設定 |
返回 URL 行為
redirect 模式下，買家一律會返回以下其中一個位置：
- session 中的
success_url（付款結算後） - session 中的
cancel_url（取消 / 放棄時） - 若你沒有設定這兩者，SDK 會回退到開啟結帳的頁面，並附加
?session_id=…&status=success|cancel
popup 與 embed 模式沒有頁面導向 — 控制權會透過
onSuccess / onCancel 回到你的頁面。請用這兩個 callback 決定
接下來要顯示什麼 UI。
CSP 與嵌入
若你使用 embed 模式，你的 CSP 必須在 frame-src 中允許我們
的來源：
Content-Security-Policy:
frame-src https://checkout.infraio.xyz https://checkout-dev.infraio.xyz;該 iframe 帶有權限政策 allow="payment; clipboard-write" — 它
只能呼叫 Payment Request API 並寫入剪貼簿，僅此而已。請不要在 iframe 上加 HTML sandbox 屬性，
否則會破壞錢包連接。該 iframe 的隔離由跨來源邊界與你的
frame-src CSP 提供。
行動裝置考量
行動版瀏覽器（尤其是 Safari）常會封鎖彈出視窗。若你的大部分流量來自
行動裝置，請使用 mode: "redirect"。在小螢幕上，彈出視窗覆蓋層也會
遮住鍵盤區域，讓挑選資產變得不方便。
白牌品牌客製化
完整白牌需要：
- SDK 上設定
hideHeader: true - 預先連接
walletAddress（買家不會看到 WalletConnect） - 在商家儀表板的 Branding 中設定你的 Logo + 品牌色
- （選用）結帳頁的自訂網域 — 例如用
pay.your-shop.com取代checkout.infraio.xyz。CNAME 驗證 通過後，在儀表板中設定即可。
下一步
- SDK → JavaScript — 各模式的完整選項 參考。
- 概念 → 工作階段 — 買家停留在頁面 時，伺服器端正在發生什麼事。
- 概念 → 支援的鏈與資產 — 選擇器中有 哪些鏈 × 資產組合可用。