結帳頁

結帳頁適合想降低前端整合成本的場景：支付頁由 StableOps 託管，負責展示鏈、資產、精確金額、收款地址和訂單狀態。商戶可以從後端為每個業務訂單建立一次性結帳頁會話，也可以在控制台建立一個可重複分享的付款連結；兩種入口最終都會為每次付款生成獨立付款訂單，並透過同一套 Webhook 生命週期通知商戶系統。

選擇收款入口

一次性會話可以把 merchantOrderId 和 metadata 直接繫結到現有業務物件，適合需要精確追蹤某一訂單的場景。付款連結儲存的是一份可重複使用的收款設定，不是一個可以反覆支付的訂單；如果每位付款人需要不同金額、客戶資訊或內部訂單號，應繼續使用一次性會話。

一次性結帳頁會話

1. 後端建立結帳頁會話：在你的伺服器端用 API 金鑰呼叫 stableops.checkoutSessions.create，傳入商戶訂單號、金額、可接受資產、展示標題、成功返回地址、取消返回地址，以及可選的 WalletConnect 專案 ID。
2. 把使用者跳轉到結帳頁：建立成功後使用回應裡的 checkout.url 做 303 跳轉，或把 URL 返回給前端再 window.location.assign(checkout.url)。
3. 使用者在結帳頁付款：託管頁面展示鏈、資產、精確金額和收款地址，並即時跟蹤狀態。使用者可以透過瀏覽器錢包、手機錢包或手動轉帳支付。無論採用哪種方式，鏈上掃描器都使用相同規則匹配轉帳。
4. 用 Webhook 完成業務動作：你的後端接收並驗籤 payment.confirmed / payment.finalized 等 Webhook 事件，再開通服務、入帳或更新訂單狀態。不要只依賴使用者跳回 successUrl，它只是前端體驗，不是最終支付憑證。

你可以透過在結帳頁 URL 上新增 lang 參數控制頁面語言，例如 ?client_secret=...&lang=es。支援的值包括 en、zh、zh-Hant、es、pt-BR、vi、id、ja。如果不傳 lang，結帳頁會盡量匹配使用者的瀏覽器語言，並兜底為英文。

可重複使用的付款連結

在控制台展開“結帳頁”選單並開啟“付款連結”頁面，點選“建立付款連結”後會開啟建立對話方塊。無需編寫程式碼，只需填寫：

• 名稱，以及可選的付款說明；
• 固定基礎金額；
• auto 或 exact 金額分配方式；
• 一組允許付款的鏈與資產，控制台會按目前沙盒或生產環境過濾可選項。

建立後，控制台會生成形如 https://pay.stableops.dev/p/{slug} 的穩定地址。你可以複製連結、在新視窗開啟，或者把它編碼成線下二維碼。付款連結預設啟用，也可以隨時停用和重新啟用。

每次開啟連結都會建立獨立訂單

付款人開啟 /p/{slug} 時，公開頁面會根據付款連結儲存的設定建立一個新的結帳頁會話和付款訂單，然後跳轉到該會話的 /c/{sessionId} 頁面。每次付款都有自己的：

• 付款訂單號、結帳頁會話號與 clientSecret；
• 精確應付金額、候選鏈與收款地址；
• 訂單有效期、確認進度和最終狀態。

同一瀏覽器標籤頁在目前會話有效期內重新整理時，會複用該次建立請求，避免因為重新整理重複佔用地址。會話過期後再次開啟連結，才會開始新的付款嘗試。

停用付款連結只會阻止它繼續建立新會話，不會取消已經生成的付款訂單或結帳頁會話。若連結被公開傳播、活動已經結束或出現異常流量，應及時停用，並檢查每條鏈的收款地址池是否仍有足夠容量。

amountMode: 'auto' 適合共享地址：只有基礎金額在所有候選共享地址上都發生衝突時，系統才會按代幣最小單位微調應付金額。exact 則始終使用固定金額；付款人仍必須支付頁面返回的 order.amount，不能少付、多付或拆成多筆。

設定結帳頁

在控制台展開“結帳頁”選單並開啟“品牌設定”頁面，可以設定以下品牌內容，並在儲存前檢視右側的基礎結帳頁預覽：

多語言聯絡文案目前支援簡體中文、繁體中文、英語、西班牙語、葡萄牙語、越南語、印度尼西亞語和日語。未填寫付款人目前使用的語言時，結帳頁使用英文文案兜底；英文也未填寫時不顯示“聯絡商戶”入口。

品牌設定按組織和環境隔離，沙盒與生產環境需要分別維護。無論會話來自後端 API 還是付款連結，建立時都會儲存一份當時的品牌快照；以後修改品牌隻影響建立會話，不會改變已經開啟或仍在處理中的會話。將某一欄位清空並儲存，可以恢復該欄位的預設顯示。

檢視結帳頁轉化漏斗

“付款連結”頁面頂部展示目前組織和環境最近 30 天的結帳頁漏斗。統計按瀏覽器會話去重，依次包括：

1. 開啟頁面：付款人開啟結帳頁頁面；
2. 載入會話：頁面成功讀取結帳頁會話；
3. 開始付款：付款人開始使用瀏覽器錢包、WalletConnect 或手動轉帳；
4. 已提交交易：錢包已經提交鏈上交易；
5. 完成付款：付款訂單到達 finalized；
6. 付款轉化率：完成付款的瀏覽器會話數除以開啟頁面的瀏覽器會話數。

付款連結列表中的“生成會話”是該連結累計建立的會話數量，“轉化率”則使用最近 30 天的頁面開啟與完成資料。漏斗用於發現頁面載入、錢包連線或付款提交環節的流失，不是財務帳本，也不能代替 Webhook、付款訂單列表與每日對帳。

支援的錢包方式

結帳頁支付頁支援以下三種支付方式，使用者可根據場景自由選擇。

瀏覽器錢包（桌面）

頁面自動檢測已注入的錢包提供者並連線，使用者確認交易後傳送。

• EVM 鏈：支援 MetaMask、Rabby 等透過 window.ethereum 注入的錢包，共 12 條鏈。
• Solana：支援 Phantom 等透過 window.phantom.solana 注入的錢包，主網 + devnet。
• TRON：支援 TronLink 等透過 window.tronLink.tronWeb 注入的錢包，主網 + Nile。

手機錢包（WalletConnect）

需要建立會話時傳入 walletConnectProjectId。結帳頁展示手機錢包列表，使用者選擇後透過 WalletConnect 二維碼或深鏈連線並簽名。支援 EVM、Solana 和 TRON 鏈——TRON 透過 WalletConnect 請求錢包對轉帳交易簽名，結帳頁再廣播上鍊。

目前控制台建立的付款連結不提供 WalletConnect 專案 ID 輸入項，因此這類連結預設只展示瀏覽器注入錢包與手動轉帳。如果需要手機錢包入口，請由後端建立一次性結帳頁會話並傳入 walletConnectProjectId。

相容的錢包：MetaMask、Trust Wallet、Coinbase Wallet、OKX、Binance Wallet、TokenPocket、TronLink、Rainbow、Zerion、Ledger Live，以及任意 WalletConnect 相容錢包。結帳頁會按訂單的鏈族過濾錢包；TRON 訂單展示支援 TRON 的錢包：Trust Wallet、TokenPocket、TronLink。

Solana 和 TRON 的錢包支付需要 RPC 節點來構造並廣播轉帳交易，結帳頁已自動處理：主網訂單經 StableOps 後端 RPC 代理轉發，但測試網訂單（Solana Devnet、TRON Nile）直連公共 RPC 節點，免費但偶爾可能限流，如果測試網支付構造失敗，稍候重試即可。

手動轉帳

任何場景都可用。使用者從頁面上覆制收款地址，在自己選擇的任意錢包或交易所傳送，鏈上掃描器按收款地址匹配入金。

後端建立會話

import { StableOps } from '@stableops/api-sdk'

const stableops = new StableOps({
  apiKey: process.env.STABLEOPS_API_KEY!,
})

const merchantOrderId = 'order_123'
const checkout = await stableops.checkoutSessions.create(
  {
    merchantOrderId,
    amount: '49.00',
    amountMode: 'auto',
    acceptedAssets: [{ chain: 'base-sepolia', asset: 'USDC' }],
    expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
    title: 'StableOps Starter Plan',
    successUrl: `https://stableops.dev?result=success&orderId=${merchantOrderId}`,
    cancelUrl: `https://stableops.dev?result=canceled&orderId=${merchantOrderId}`,
    walletConnectProjectId: process.env.WALLETCONNECT_PROJECT_ID,
  },
  { idempotencyKey: 'order_123' },
)

return Response.redirect(checkout.url!, 303)

參數建議

• merchantOrderId：使用你係統裡的訂單號，並同時作為冪等鍵，避免重複建立。
• amountMode: 'auto'：讓 StableOps 自動微調金額，降低共享收款地址下的撞單機率。
• acceptedAssets：先從測試網資產開始；生產環境再切到你實際支援的主網資產。
• successUrl / cancelUrl：只用於使用者體驗。最終業務狀態以 Webhook 為準。
• walletConnectProjectId：可選，可在 Reown Cloud 免費註冊取得。傳入後，結帳頁展示手機錢包入口，EVM、Solana 和 TRON 鏈均透過 WalletConnect 二維碼或深鏈連線手機錢包簽名：
  • EVM 和 Solana 鏈：MetaMask、Trust Wallet、Coinbase、OKX、Binance Wallet、Rainbow、Zerion、Ledger Live 及通用 WalletConnect。
  • TRON 鏈：Trust Wallet、TokenPocket、TronLink。錢包透過 WalletConnect 對轉帳交易簽名，結帳頁再廣播上鍊。
  • 不傳時不展示手機錢包入口（EVM / Solana / TRON 均不展示）；使用者仍可用瀏覽器注入錢包或手動轉帳支付。
• metadata：可以放方案、使用者 ID、內部訂單標籤等，但公開結帳頁不會展示訂單後設資料。

線上測試

下面的測試面板會直接在瀏覽器裡使用你的沙盒 API 金鑰建立結帳頁會話，並跳轉到公開結帳頁頁面。你可以自定義商戶訂單號、金額、標題、描述、返回地址和訂單後設資料，方便驗證商戶側參數會如何進入支付頁。

安全注意

• 這個面板只用於沙盒測試。生產環境請在你的後端建立結帳頁會話，不要在瀏覽器暴露生產 API 金鑰。
• clientSecret 是開啟公開支付頁的憑證，只應該傳送給本次付款使用者。
• 結帳頁頁面只讀取公開會話，不需要 Clerk 登入，也不會暴露訂單後設資料。
• 付款連結本身不包含 API 金鑰或 clientSecret，但它是公開且可重複使用的入口；任何拿到地址的人都可以發起新的付款嘗試。只在預期管道分享，並監控地址池容量與轉化漏斗。
• 停用付款連結不能撤銷已經生成的付款訂單。需要停止一筆現有訂單時，應按付款訂單自身的狀態和取消規則處理。

處理 Webhook

結帳頁與 SDK 流程走的是同一套付款訂單，支付狀態始終透過 Webhook 到達——不要只信任 successUrl 跳轉。

• Webhooks —— 事件型別、負載結構、投遞/重試行為。
• 驗證 Webhook 簽名 —— 在解析 body 前校驗 X-Product-Signature。
• Webhook 排障 —— 排查漏投/失敗的投遞。