結帳 — 總覽
託管結帳是買家實際送出資金的頁面。你不需要自己渲染資產
選擇器、存款位址或 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 預先提供好的 已連接錢包付款。
- 狀態脈動指示 — 「等待轉帳中」、「偵測到交易（3/12 確認）」、「已付款」。
- 取消按鈕（一律顯示）→ 觸發
onCancel。
自訂頁面
| 選項 | 做法 | 限制 |
|---|---|---|
| 隱藏訂單摘要 | SDK 上設定 hideSummary: true | 買家仍可在存款面板中看到總額 |
| 隱藏 InfraIO 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 並寫入剪貼簿，僅此而已。它不會
套用 HTML sandbox：結帳頁是一個完整的錢包連接應用程式，其
postMessage 安全機制（雙方都會做來源檢查）以及第三方錢包 SDK
（WalletConnect、Coinbase、MetaMask）都需要一個真正的
same-origin 指令碼情境，所以套上 HTML sandbox 屬性只會破壞
錢包連接，換來的隔離收益卻微乎其微。隔離性改由跨來源邊界、
嚴格的 postMessage 來源檢查，以及你的 frame-src CSP 來提供。
行動裝置考量
彈出視窗在行動版 Safari 上會被積極封鎖。若你的流量以行動裝置
為主，請預設使用 mode: "redirect"。彈出視窗覆蓋層在小螢幕上
也會遮住鍵盤區域 — 用來輸入金額還好，但用來挑選資產就不太
方便。
品牌客製化（給白牌需求的團隊）
完整白牌需要：
- SDK 上設定
hideHeader: true - 預先連接
walletAddress（買家不會看到 WalletConnect） - 在商家儀表板的 Branding 中設定你的 Logo + 品牌色
- （選用）結帳頁的自訂網域 — 例如用
pay.your-shop.com取代checkout.infraio.xyz。CNAME 驗證 通過後即可透過儀表板自助設定。
下一步
- SDK → JavaScript — 各模式的完整選項 參考。
- 概念 → 工作階段 — 買家停留在頁面 時，伺服器端正在發生什麼事。
- 概念 → 支援的鏈與資產 — 選擇器中有 哪些鏈 × 資產組合可用。