如何在不託管資金的情況下接受 USDC：生產級架構

接受 USDC 付款並不要求把收款資金交給支付服務商控制。商戶提供並控制收款錢包，客戶把 USDC 直接轉入這些地址。

但非託管只解決資金控制權，不會消除支付營運層。一套非託管 USDC 支付接入仍需要明確的業務訂單、精確的鏈和資產付款指令、轉帳匹配、確認與最終性跟蹤，以及能夠安全觸發履約的已驗證事件。StableOps 負責訂單和事件層；你的應用仍是客戶業務訂單的權威，商戶仍控制收款錢包。

如果還在確定整體收款模式、資產範圍和上線步驟，可先閱讀企業如何接受穩定幣支付；本文只深入非託管 USDC 架構。

生產架構應把資金和支付狀態分開

錢包只能回答“代幣到了哪裡”，不能回答“這筆轉帳支付了哪個購物車、是否按時、現在能否發貨”。這些職責需要明確分層：

控制流：商戶後端 -> StableOps API -> Payment Order -> Checkout 或自定義 UI
資金流：付款錢包 -> 區塊鏈轉帳 -> 商戶控制的收款地址
事件流：區塊鏈 -> StableOps 掃描器 -> 簽名 Webhook -> 商戶後端
                                                       |
                                                       v
                                                  業務訂單 / 履約

商戶後端建立並擁有業務訂單。StableOps 建立 Payment Order，從商戶的收款地址池分配候選地址，並返回與鏈對應的付款指令。Hosted Checkout 或你的 UI 向客戶展示這些指令。客戶轉帳後，StableOps 觀察並歸一化鏈上事件，推進確認狀態，再向伺服器端傳送簽名 Webhook。

在這個模型中，資金不經過 StableOps。StableOps 也不會替商戶決定是否發貨、開通權益或寫入帳本；你的應用在驗證支付事件後，依據持久化的業務狀態作出決定。

開始前，應按照 Quickstart 匯入足夠的收款地址並註冊 Webhook 端點。地址容量屬於生產依賴：如果某個鏈和資產沒有可用的候選地址，系統就無法發出完整付款指令。

先建立業務訂單，再建立付款訂單

先持久化購物車、發票或訂閱帳單。將其不可變 ID 用作 merchantOrderId，並把已經儲存的金額和過期時間作為 Payment Order 輸入。這樣，重試就有穩定身份，重新整理瀏覽器也不會生成條款不同的第二次收款嘗試。

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

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

export async function createUsdcPayment(order: {
  id: string
  amount: string
  paymentExpiresAt: string
}) {
  return stableops.paymentOrders.create(
    {
      merchantOrderId: order.id,
      amount: order.amount,
      acceptedAssets: [{ chain: 'base', asset: 'USDC' }],
      expiresAt: order.paymentExpiresAt,
    },
    { idempotencyKey: `payment-order:${order.id}` },
  )
}

每次重試都必須複用相同的 merchantOrderId、金額、可接受資產、過期時間和冪等鍵。不要在每次請求時重新計算過期時間或生成隨機鍵。應把 order.amount 與選中的 paymentInstructions 條目組合起來，展示準確的金額、鏈、資產和地址。如果以後啟用 amountMode: 'auto'，這個區別尤其重要，因為返回的 order.amount 可能不同於請求時的基準金額。這些值是付款指令，不是已經付款的證據。

Payment Orders 指南解釋了地址分配和生命週期。如果希望由 StableOps 承載錢包互動和進度 UI，可以在相同訂單模型上建立 Hosted Checkout Session。需要框架級示例時，可閱讀如何在 Next.js 中接受 USDC 支付。

匹配完整付款指令，而不是錢包餘額

生產級匹配需要同時使用訂單的鏈、資產、收款地址和預期金額。只檢查錢包餘額是否增加，會丟失轉帳與業務訂單之間的關係。當多個客戶支付相同金額、USDC 存在於多條支援鏈，或者轉帳在訂單過期後才到達時，餘額模型會產生歧義。

應把展示給客戶的資訊看成一個不可拆分的元組：

(付款訂單, 鏈, 資產, 地址, 金額, 過期時間)

客戶必須在指定鏈上傳送指定資產。客服和營運策略還應分別覆蓋錯誤網路、錯誤資產、少付、多付和遲到轉帳。不要把無法匹配的轉帳靜默解釋成某個恰好還未關閉的訂單付款。

使用最小支付狀態機

鏈上觀察是一個過程，而不是一個布林型 paid 欄位。每個狀態允許的應用行為不同。

確認策略取決於具體鏈和產品風險。確認狀態模型詳細解釋了確認、最終性與鏈重組之間的關係。

Checkout success URL 只是瀏覽器返回路徑。錢包顯示“已提交”和交易雜湊可以用於展示進度或調查，但都不能證明付款已經最終完成。不可逆履約必須等待已驗籤、已去重的 payment.finalized Webhook。

把 Webhook 邊界做成持久化流程

先讀取未經修改的原始 request body，驗證簽名後再解析 JSON。在同一個資料庫事務中，把 X-Event-Id 插入帶唯一約束的表，並同時更新持久化業務狀態，或者寫入 outbox/履約任務；只有事務提交成功後才能返回 2xx。此時唯一鍵衝突才表示事件及其持久化後續動作都已提交，端點可以返回成功而不重複入隊。

事件去重與履約冪等解決的是不同故障。事件 ID 阻止重試或重放把同一事件應用兩次；按內部訂單 ID 設計的冪等履約，則阻止兩條合法程式碼路徑重複發貨或重複授予權益。

外部履約通常不能放進這個資料庫事務。應由 worker 領取已經提交的 outbox 任務，按內部訂單 ID 冪等執行副作用，再記錄完成狀態；對帳 worker 負責恢復程序崩潰後仍處於可重試狀態的任務。Webhook 處理器應足夠短，以便可靠返回 2xx；驗籤、重試、重放和投遞審計細節見 Webhook 指南。

保留可對帳的關聯記錄

每次收款嘗試都應儲存以下關係：

• 內部業務訂單 ID；
• StableOps Payment Order ID；
• 選定的鏈、資產、地址、金額和過期時間；
• 每個 X-Event-Id 及其事件型別；
• 鏈上交易雜湊。

這些記錄既能讓 worker 在故障後恢復，也能讓客服不依賴錢包餘額回答付款發生了什麼。定時對帳任務應查詢已經最終完成但履約未完成的付款、超過預期時間仍待處理的訂單，以及已經記錄事件但下游任務失敗的情況。

生產檢查清單

• 明確產品接受的鏈與 USDC 組合；只有“USDC”並不等於已經選擇網路。
• 保持足夠的合格收款地址；對單次使用地址池，應在可用容量耗盡前告警；對共享地址池，則應監控金額衝突與精確金額匹配。
• 呼叫 StableOps 前持久化訂單金額、過期時間、可接受資產和冪等鍵。
• 為過期、遲到、錯誤鏈、錯誤資產、少付和多付制定處理策略。
• 只有在風險合理時才把可撤銷動作對映到 confirmed；不可逆履約留給 finalized。
• 從原始 body 驗證 Webhook，把金鑰儲存在伺服器端，並規劃金鑰輪換。
• 對 X-Event-Id 建立唯一約束，按業務訂單 ID 保證履約冪等。
• 測試重複投遞、重放、程序崩潰和 payment.reverted 處理。
• 定時對帳業務訂單、Payment Order、事件和交易雜湊。

FAQ

接受 USDC 付款需要託管客戶或商戶的錢包嗎？

不需要。付款人從自己控制的錢包發起轉帳，商戶提供收款地址。StableOps 管理付款訂單、地址分配、鏈上觀察和事件，但不持有商戶收到的資金，也不接觸客戶私鑰。

可以用一個錢包地址接收所有 USDC 付款嗎？

它當然可以接收轉帳，但會增加可靠匹配和客服處理的難度。獨立分配的地址能更清楚地關聯訂單與轉帳。如果地址策略使用共享地址，匹配模型仍必須用鏈、資產、金額和訂單關係消除歧義。

USDC 付款什麼時候可以安全履約？

不可逆履約應在伺服器端驗籤並去重 payment.finalized Webhook 後執行。payment.detected 和 payment.confirmed 可用於展示進度或執行謹慎的可撤銷動作，但不能代替最終付款憑據。

從一個完整付款閉環開始

按照 Quickstart 在 Sandbox 建立一個業務訂單，用穩定冪等鍵建立對應 Payment Order，完成一次測試 USDC 轉帳，再把一個經過驗證的 payment.finalized 處理器連線到冪等履約任務。確認這個閉環能承受重複投遞和重放後，再擴充套件到更多鏈、資產與結帳介面。如果還在判斷是否也應開放 USDT，可用面向商戶的 USDC 與 USDT 收款對比核對客戶分佈、儲備風險與資金路徑。