一筆 PolyPay 託管支付如何完成

按照實際程式碼流程說明 Hosted Checkout 提供方選擇、Stripe Checkout、加密貨幣結算與簽名 Webhook 投遞。

最近一次對照 PolyPay 實現稽核：2026 年 8 月 31 日。

Stripe 授權與 Stripe Checkout 除配置的灰度規則外，還要求商戶具備有效付費或按量套餐。只有套餐、商戶連線與收付款能力均就緒後，Hosted Checkout 才會展示 Stripe。

支付生命週期概覽

1. 商戶使用商戶訂單號、金額、資產、網路和可選回撥地址建立訂單。
2. Hosted Checkout 只展示當前訂單真正可用的 Stripe、Crypto 或兩者。
3. 商戶先透過 OAuth 授權已有的 Stripe Standard 帳戶。選擇 Stripe 時，PolyPay 建立服務端 Payment Attempt，並在該商戶帳戶作用域建立 Direct Charge Checkout Session；Charge、餘額、退款和爭議均留在商戶 Stripe 中。選擇 Crypto 時分配已啟用的收款錢包和精確應付金額，並記錄獨立的 Payment Attempt。
4. Stripe 由簽名 Provider Webhook、Connected Account 主動回查和陳舊嘗試定時補償共同確認；Crypto 由鏈監聽器獨立確認。
5. 只有第一個完成驗證的 Provider 能把訂單推進為已支付並觸發一次履約。隨後確認的 Stripe 或 Crypto 支付會進入去重的人工處置佇列，不會再次履約；商戶只收到一次已支付 Webhook。

1. 建立訂單與冪等

商戶傳入的 mch_order_id 在商戶和部署自動選擇的支付隔離範圍內唯一。商戶建立訂單時不需要選擇或提交環境，Hosted Checkout 會自動使用當前部署已連線的 Stripe 帳戶。重複請求一個仍有效的訂單時，系統返回已有訂單，而不是靜默建立另一個待付款訂單。訂單過期後，Hosted Checkout 可以複用同一商戶訂單號，並在重新選擇支付方式後建立新的支付嘗試。響應包含 trade_id、actual_amount、address、expiration_time 和 payment_url。

在 Hosted Checkout 選擇 Stripe 或 Crypto

Stripe 與 Crypto 同時可用時，付款人先選擇一級 Provider，再繼續選擇加密資產和網路；只有 Crypto 可用時，Hosted Checkout 會跳過 Provider 層，直接進入資產與網路選擇。只有當商戶具備有效付費或按量套餐、連線狀態可用、收款與結算能力就緒、商戶開關已開啟，並且訂單滿足幣種、金額和灰度規則時，Stripe 才會出現。套餐過期後，已儲存的 Stripe 連線和開關會保留但凍結：Hosted Checkout 隱藏 Stripe，建立新 Stripe 嘗試也會被拒絕；恢復有效套餐後自動恢復。選擇 Stripe 後，訂單從“等待選擇支付方式”進入“等待支付”，並建立 pending Payment Attempt；從 Stripe 返回時，服務端會失效未支付 Session、取消該嘗試並恢復支付方式選擇。如果 Stripe 等待支付期間重新開啟原支付連結，Hosted Checkout 會展示 Provider 選擇，而不是展示欄位為空的加密貨幣支付頁；再次選擇 Stripe 時會安全複用當前有效的 Stripe attempt。Stripe Checkout 使用服務端儲存的訂單金額，瀏覽器不能覆蓋。Stripe 回跳頁只輪詢服務端 Payment Attempt，不會根據 URL 引數把訂單標記為已支付。

Hosted Checkout 使用 GET /api/v2/checkout/orders/{trade_id}/payment-providers 查詢一級 Provider；使用 POST /api/v2/checkout/orders/{trade_id}/payment-attempts 並傳 provider=stripe 建立 Stripe 嘗試；使用 GET /api/v2/checkout/payment-attempts/{attempt_id} 輪詢狀態。具備有效付費或按量套餐的商戶可在 /api/v1/pay/merchant/payment-providers/stripe 下授權已有 Standard 帳戶、提交一次性 OAuth 回撥、重新整理狀態、啟停和撤權。凍結期間仍可讀取 status，但免費或過期套餐呼叫管理介面會被拒絕。PolyPay 只儲存 acct_ 標識，不儲存商家的 Stripe Secret Key 或 OAuth Token；平臺將日常支付使用的 Restricted Key 與僅用於 OAuth 換碼和撤權的完整 Secret API Key 分開儲存。connect、enable、disconnect 必須攜帶已認證的 step-up ticket。

2. 分配 Crypto 收款錢包與精確金額

PolyPay 從支援目標資產和網路的商戶已啟用錢包中選擇地址，並在訂單有效期內鎖定“錢包 + 金額”組合。因此付款方必須傳送 actual_amount，接入方不應自行重新計算或取整。

選擇支付方式時的參考網路手續費

未預設幣種和網路時，只要商戶支援 USDT，Hosted Checkout 就預設選中 USDT。預設收款錢包支援 USDT 時，選中並置頂該錢包網路；否則優先選擇 TRON，再使用其他首個支援 USDT 的網路。選擇 USDC 時，Ethereum 緊接預設錢包網路之後。預設網路與常用網路相同時只出現一次。商戶不支援 USDT 時，才使用預設錢包的優先幣種。幣種卡片始終使用產品固定順序，不因預設錢包改變排列。付款方每次切換幣種時，Hosted Checkout 都自動選中該幣種排序後的第一個網路，付款方仍可改選其他相容網路。支付方式響應會按資產和網路返回短時有效的 fee_quotes。PolyPay 從鏈 RPC 或費率介面同步實時單位費率，結合標準轉帳資源模型計算參考值，並按手續費幣種的實時 USD 行情返回 standard_fee_usd。Base 與 Optimism 還會加入 OP Stack GasPriceOracle 返回的代表性 L1 資料費和 Operator Fee。available 表示當前有效，stale 表示本次重新整理失敗後保留的最近成功觀測，unavailable 表示不應展示數值。Hosted Checkout 為保持選擇介面簡潔，不展示手續費估算；最終網路手續費以錢包顯示為準。

無需登入即可呼叫 GET /api/v1/pay/public/network-fees，查詢全部支援轉帳型別的較低、標準和快速手續費；PolyPay Tools 使用同一資料，橫向對比 USDT、USDC 與各網路本位幣的標準速度估值。 開啟實時手續費查詢工具.

公開 GET /api/v1/pay/public/platform-stats 介面為官網提供脫敏的當前監聽狀態，只返回統一支付網路與資產數量、各監聽器目前已完成的最高區塊、落後區塊數，以及正常、降級、中斷或未知狀態；不返回錢包地址、交易 Hash、RPC 詳情或內部錯誤。監控停用、資料不完整或快照過期時，官網顯示狀態暫不可用，不使用示例資料替代。

收款錢包地址審查

PolyPay 會在後臺靜默審查新新增的錢包，以及修改了地址或網路的錢包；錢包管理頁面不會展示中間審查狀態。地址確認屬於交易所或託管平臺後，錢包會被禁用，且不能編輯或重新啟用。錢包管理頁面透過禁用原因連結提供申訴和客服入口；只修改名稱、幣種和監聽金額範圍不會重新觸發審查。

3. 使用 WalletConnect 或頁面地址付款

對於 TRON 與 EVM 網路上受支援的 USDT、USDC 訂單，託管收銀臺可以透過 WalletConnect 調起相容錢包，要求錢包傳送精確的代幣轉帳。普通收款二維碼在桌面端保持展示；移動端預設收起，透過“使用另一臺裝置掃碼”按需展開，讓精確金額和收款地址保持在主要位置。TRON 帳戶的 Active Permission 需要多份簽名時，收銀臺先收集 TronLink 第一簽並建立短時跨裝置會話，再展示二維碼供授權共同簽名人確認；該多籤二維碼仍是移動端流程的必需步驟。手機對完全相同的交易追加簽名，透過 getSignWeight 確認累計權重達到閾值後才廣播。瀏覽器可以展示錢包返回的交易 Hash，但不會把 Hash 作為付款證據提交給 PolyPay。PolyPay 由鏈監聽器獨立發現轉帳，匹配訂單鎖定的網路、代幣合約、收款地址和整數最小單位金額，並在達到所需確認數後才更新訂單狀態。二維碼與手動複製地址也使用同一條服務端掃鏈確認路徑。

4. 可觀察的訂單狀態

5. Webhook 投遞與驗籤

Stripe 事件進入 PolyPay 後，系統先使用對應環境的 destination secret 驗證 Stripe-Signature，冪等儲存 Provider Event，校驗 Connected Account 作用域，並主動回查 Checkout Session 或 Charge 後才推進狀態。隨後 PolyPay 使用 Ed25519 v2 為商戶回撥簽名。接入方應根據 Key ID 從平臺 JWKS 選擇公鑰，驗證簽名覆蓋的商戶 ID、環境、時間戳、nonce 和原始請求體。非 2xx 響應會被視為投遞失敗。接入方應儲存 event ID，並對每個事件做冪等處理。

6. 選擇正確的事實來源

瀏覽器跳轉只用於改善客戶體驗，不是付款證明；Stripe Checkout 和 Crypto 錢包跳轉都遵循這一規則。商戶應透過驗籤後的 PolyPay Webhook 或鑑權訂單狀態查詢更新業務訂單。Provider 與商戶 Webhook 都可能重複投遞，因此履約邏輯必須冪等。

責任邊界

商戶

持有收款錢包與已連線的 Stripe 帳戶、保護 API 憑據、在 Stripe Dashboard 處理退款和爭議、驗證 PolyPay Webhook，並冪等履行業務訂單。

PolyPay

建立和跟蹤支付訂單、在商家帳戶作用域建立 Direct Charge Checkout、驗證 Provider 事件、分配 Crypto 付款資訊、監聽已配置鏈，併傳送簽名狀態事件；PolyPay 不接收商家的 Stripe 資金，也不收取 Application Fee。

付款方

在訂單過期前使用頁面顯示的正確網路、地址、資產和精確金額。

具體接入請繼續閱讀 API Key 指南和 Webhook 安全指南。 API Key · Webhook Security

FAQ