付款連結 — 總覽

付款連結是一個可分享的 URL，會把買家導向一個你已經設定好的 託管結帳頁。不需要 SDK，也不需要伺服器整合 — 在儀表板中發行、 分享出去，資金在鏈上確認時就會觸發同一個 payment.settled webhook。

從底層來看，付款連結就是一個 CheckoutSession — 「付款連結」只是儀表板端對「非由買家驅動的 SDK 流程所建立的 session」的稱呼。webhook 契約相同、鏈上結算方式相同、費用也 相同。

常見用途：

• 不用寫程式，就能對一次性客戶開立請款單
• 業務團隊本季沒空串接客製購物車的銷售頁面
• B2B 後續請款 — 把連結貼進 email，就算完成
• 「請我喝杯咖啡」風格的固定金額打賞頁面

建立一個付款連結

目前只能透過儀表板建立：

1. 登入商家儀表板 
2. Payments → Payment Links → + New link
3. 選擇下列兩條路徑之一：
   • New order — 輸入商品項目、幣別、客戶資訊，以及選填的 metadata。儀表板會在同一次呼叫中同時建立 Order 與付款 連結。
   • Existing order — 選一個 PENDING 的訂單（例如買家放棄 了前一個連結）。系統會重新發行一個新連結，並掛在同一筆 訂單上，讓訂單歷史保持完整。
4. 儲存 → 儀表板會顯示 https://checkout.infraio.xyz/cst_… URL，附上複製按鈕與可下載的 QR code。測試模式的連結會使用 checkout-dev.infraio.xyz，讓環境直接編碼在主機名稱中。

買家會看到什麼

1. 買家會抵達 checkout.infraio.xyz/<session_key> — 與 SDK 發行的 session 完全相同的託管結帳 UI。
2. 買家會經歷結帳 — 總覽中所描述的 標準流程：選資產 → 送出資金 → 等待確認。
3. payment.settled 會觸發你的 webhook，帶著訂單、intent、 收據、鏈上交易雜湊與確認數 — 與任何其他已結算付款的酬載 完全相同。schema 請見 Webhooks。

儀表板能提供什麼

付款連結目前在儀表板上提供：

• 列表檢視 — 你發行過的每一個連結，採游標分頁，顯示狀態、 金額、所屬訂單編號、客戶、到期時間，並可一鍵開啟買家看到的 URL。
• 篩選器 — 狀態（ACTIVE / COMPLETED / EXPIRED / CANCELED）、日期區間，以及跨訂單編號、客戶姓名、email 或 外部參考的全文檢索。
• CSV 匯出 — 一鍵匯出，會套用目前的篩選條件。
• KPI 摘要條 — 依環境（live 或 test，透過 X-Environment 標頭區分）分別統計各狀態的數量，確保數字 永遠與表格所顯示的一致。
• 詳情頁 — 訂單摘要、session 歷史（這筆訂單的每一次嘗試）、 帶區塊瀏覽器連結的鏈上歷史，以及針對付款前過期的 session 提供 的重新建立連結操作。

目前的限制

• 沒有程式化 API — 連結必須在儀表板中建立。SDK 可以透過 POST /b2b/v1/checkout-sessions/quick 建立等效的單次使用 session（見 API 參考），但「長期有效、 可分享的 URL」這種體驗目前僅限儀表板。
• 沒有逐買家的身分驗證 — 任何拿到這個 URL 的人都可以付款。 單次使用的機制部分緩解了這個問題；完整的買家身分綁定在下方 的路線圖上。
• 品牌設定是全域的 — 連結會使用你在設定 → Branding 中設定的商家層級 Logo、品牌色與邊框圓角。目前儀表板 UI 尚未 提供逐連結的品牌覆寫。

路線圖

我們已知想做的項目，依優先順序由高到低排列：

• 程式化建立 — 一個 POST /b2b/v1/payment-links endpoint， 對應儀表板雙頁籤對話框的功能，並回傳相同的 checkout_url。 會自然搭配列表查詢與撤銷功能一起推出。
• 依時間到期 — 連結在特定日期之前都有效，而不只是等 session 的 TTL 到期。對於「14 天內到期」這種請款流程是必要的。
• 可重複使用的連結 — 類似 Stripe 風格、可供多個買家使用的 頁面（捐款、打賞、訂閱式帳單）。目前每個連結都是單次使用。
• 逐買家身分 — 把連結鎖定在特定 email 或錢包上，讓它無法被 轉發。
• API 端 QR code 產生 — 目前 QR code 是在儀表板前端產生 的；讓 API 也能產生，以支援標籤列印與內嵌收據，已列入計畫。

另請參閱

• 概念 → 工作階段 — 買家付款期間， session 與 intent 層發生了什麼事。
• 結帳 — 總覽 — 買家實際看到的畫面。
• Webhooks → 總覽 — 你的伺服器要回應 的 payment.settled 事件。