<!-- Source: https://docs.infraio.xyz/zh-TW/checkout/overview -->
<!-- Last updated: 2026-10-04 -->

# 結帳 — 總覽

**託管結帳頁**是買家實際送出資金的頁面。你不需要自己渲染資產
選擇器、每筆訂單獨立收款位址(CREATE2)或 QR code — SDK 會開啟我們的頁面（位於
`https://checkout.infraio.xyz/<session_key>`），UI 由我們處理。

## 三種模式

- [Popup](https://docs.infraio.xyz/zh-TW/sdks/javascript#popup) — 置中的覆蓋式彈出視窗，預設約 560×780。商店頁面維持原狀。 付款完成、彈出視窗關閉時觸發 `onSuccess`。預設模式。
- [Redirect](https://docs.infraio.xyz/zh-TW/sdks/javascript#redirect) — 直接導向結帳頁。最適合彈出視窗被封鎖的瀏覽器，或是覆蓋層 體驗不佳的行動網頁。買家會透過 session 中的 `success_url` / `cancel_url` 返回。
- [Embed](https://docs.infraio.xyz/zh-TW/sdks/javascript#embed) — 內嵌在你頁面中的 iframe。適合你想端到端控制版面、不想有 情境切換的場景。透過 postMessage 自動調整大小。

## 選擇模式的判斷準則

| 情境… | 使用 |
| --- | --- |
| 桌面網頁，一般電商情境 | **Popup** |
| 行動網頁 | **Redirect**（行動裝置上 popup 常被封鎖） |
| 有嚴格 CSP 限制的後台系統 | **Redirect** |
| App 內 webview / 頁面內原生結帳 | **Embed** |
| 想要完全自訂、帶白牌 header 的買家流程 | **Embed** + `hideHeader` + 你自己的錢包連接 |

## 買家會看到什麼

無論哪種模式，頁面都會呈現：

1. **訂單摘要**（商品項目、總額、幣別）。若你已在自己那端顯示
   過，可用 `hideSummary` 隱藏。
2. **資產選擇器** — 你在商家設定中啟用的鏈 × 資產組合清單。買家
   從中挑一個。
3. 所選組合的**獨立收款位址 + QR code + 金額**。買家可以掃描、連接
   錢包（WalletConnect 按鈕），或直接用你透過 SDK 預先提供好的
   已連接錢包付款。在 TRON、Solana 與 TON 上，買家直接付款到你的資金庫錢包；請見[直達錢包的網路](https://docs.infraio.xyz/zh-TW/concepts/chains#直達錢包的網路)。
4. **狀態脈動指示** — 「等待轉帳中」、「偵測到交易（3/12
   確認）」、「已付款」。
5. **取消**按鈕（一律顯示）→ 觸發 `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` 中允許我們
的來源：

```http
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"`。在小螢幕上，彈出視窗覆蓋層也會
遮住鍵盤區域，讓挑選資產變得不方便。

## 白牌品牌客製化

完整白牌需要：

1. SDK 上設定 `hideHeader: true`
2. 預先連接 `walletAddress`（買家不會看到 WalletConnect）
3. 在商家儀表板的 Branding 中設定你的 Logo + 品牌色
4. （選用）結帳頁的自訂網域 — 例如用
   `pay.your-shop.com` 取代 `checkout.infraio.xyz`。CNAME 驗證
   通過後，在儀表板中設定即可。

## 下一步

- [SDK → JavaScript](https://docs.infraio.xyz/zh-TW/sdks/javascript) — 各模式的完整選項
  參考。
- [概念 → 工作階段](https://docs.infraio.xyz/zh-TW/concepts/sessions) — 買家停留在頁面
  時，伺服器端正在發生什麼事。
- [概念 → 支援的鏈與資產](https://docs.infraio.xyz/zh-TW/concepts/chains) — 選擇器中有
  哪些鏈 × 資產組合可用。