穩定幣支付確認數如何設計 | StableOps Blog

穩定幣支付看起來像一筆簡單轉帳，但商戶系統真正需要的是一個可以履約、可以審計、可以回放的業務事件。確認數設計的目標不是追求絕對速度，而是在使用者體驗和鏈上回滾風險之間給出清晰邊界。

這篇文章給支付、訂單和風控團隊一個共同的決策框架：什麼時候只更新前端狀態，什麼時候可以發放低風險權益，什麼時候才可以把交易寫入不可逆的業務帳本。鏈的具體確認數會隨網路和平台設定變化，因此不要把某個數字硬編碼在業務服務裡；讓業務動作跟隨統一的支付事件。

為什麼不能只看一筆交易

錢包廣播成功只說明交易進入網路傳播階段。即使交易已經出現在區塊瀏覽器中，也可能遇到交易替換、鏈重組或節點短暫不一致。商戶系統如果在這一刻就開通權益，後續很容易出現“使用者已經拿到商品，但付款從帳上消失”的難以解釋的狀態。

StableOps 把鏈上轉帳拆成四個明確狀態：

detected：掃描器已經在區塊中看到可匹配的候選轉帳。它適合驅動“已收到，確認中”的使用者介面，但不代表資金已經可靠。
confirmed：交易達到目前鏈的業務確認閾值。它適合低風險、可撤銷的履約動作。
finalized：交易達到更強的最終性閾值。它是對帳、記帳和不可逆履約的預設觸發點。
reverted：確認跟蹤期間發現鏈上事實被回滾，或收據執行失敗。之前基於這筆交易做的樂觀處理都需要被撤銷或複核。

這個模型的關鍵是把“鏈上看到交易”和“業務可以承諾結果”分開。前者是技術觀察，後者是產品承諾；兩者之間必須有狀態機，而不是一個布林值。

確認閾值是產品策略

不同業務可以接受的等待時間不同。低額 API 餘額充值可能在較低確認數後可用，高額訂閱、提幣額度提升或交易入金則應等待更強確認。這裡需要先回答的不是“某條鏈要等幾塊”，而是“這次動作一旦做錯，是否能低成本撤銷”。

可以用三個問題為產品動作分級：

這筆錢對應的權益能否撤銷，例如臨時試用、站內餘額或優惠券？
發生回滾時，商戶是否能追回價值，還是會變成真實損失？
使用者是否能接受等待，還是必須先看到“正在確認”的明確反饋？

第一版建議把確認策略放在平台層統一設定，業務系統只消費標準化事件。這樣下游不需要理解每條鏈的出塊時間、RPC 延遲和重組特徵，只需要處理穩定的 Webhook 狀態機。具體確認和最終性定義可隨時參考確認狀態說明。

一個常見的策略劃分如下：

業務場景	推薦觸發狀態	原因
支付頁提示、客服通知	`detected`	提前反饋，但不改變資產或權益
小額、可撤銷的站內餘額	`confirmed`	在體驗和風險之間折中
數字商品、帳戶升級、訂閱開通	`finalized`	使用者拿到的權益不應依賴可回滾交易
實物發貨、提幣、法幣結算	`finalized`	風險高且補償成本高

不要把這個表當成唯一規則。高風險行業、受監管資金流或異常帳戶，可以在同一狀態機上疊加風控稽核；反過來，促銷活動中的小額權益也可以選擇在 confirmed 後先行發放。重要的是讓例外成為顯式策略，而不是散落在各個訂單服務裡的臨時判斷。

把事件狀態對映到履約動作

訂單系統應儲存自己的業務狀態，但支付狀態應以 StableOps 的事件流為事實來源。每個事件都應該只有一個清晰的業務動作和一個明確禁止的動作：

事件	對使用者展示	後端應做什麼	此時不要做什麼
`payment.detected`	已收到支付，確認中	記錄鏈上交易、重新整理訂單頁	發貨、開通不可逆權益
`payment.confirmed`	支付已確認	允許低風險履約或進入風控佇列	假設交易已經最終不可逆
`payment.finalized`	支付完成	寫入收款帳本、觸發正式履約	再次依賴前端輪詢決定結果
`payment.reverted`	支付未完成	停止後續履約、執行補償或人工複核	靜默忽略已經發出的樂觀動作
`payment.expired`	訂單已過期	關閉收款入口、引導重新下單	繼續等待原訂單

一個實用的邊界是：前端可以用 detected 降低等待焦慮，訂單服務可以用 confirmed 做可撤銷的預處理，而帳務和不可逆履約只消費 finalized。這樣即使某次事件延遲或重放，系統仍然知道每個階段允許做什麼。

如果業務必須主動查詢狀態，也應該把查詢結果寫回同一套狀態轉換邏輯，而不是繞過事件處理器直接修改訂單。Webhook 是主路徑，輪詢只是故障恢復和對帳補償手段。

Webhook 必須冪等

確認事件應按 at-least-once 投遞設計。網路超時、服務重啟和平台重放都會讓同一事件多次到達。下游系統需要用事件 ID 去重，而不是假設同一事件只到達一次，更不能僅憑“訂單目前看起來已經成功”跳過處理。

一個可靠的 handler 應按下面的順序工作：

讀取原始 request body，並先驗證簽名。
缺少 X-Event-Id 或 JSON 無效時拒絕請求，不要確認一個無法安全處理的事件。
在同一個資料庫事務中插入唯一事件記錄、找到內部訂單、驗證合法狀態遷移，並更新持久化狀態或寫入 outbox 任務。
只有事務提交後才返回 2xx；外部副作用交給後台 worker，按內部訂單 ID 冪等執行。

import {
  EVENT_ID_HEADER,
  SIGNATURE_HEADER,
  verifySignature,
} from '@stableops/api-sdk/webhooks'

export async function POST(req: Request) {
  const rawBody = await req.text()
  const verification = verifySignature({
    secrets: [process.env.STABLEOPS_WEBHOOK_SECRET!],
    header: req.headers.get(SIGNATURE_HEADER) ?? undefined,
    rawBody,
  })

  if (!verification.ok) return new Response('invalid signature', { status: 400 })

  const eventId = req.headers.get(EVENT_ID_HEADER)
  if (!eventId) return new Response('missing event id', { status: 400 })

  let event: {
    type: string
    data: { payment_order_id?: string; merchant_order_id?: string }
  }
  try {
    event = JSON.parse(rawBody)
  } catch {
    return new Response('invalid JSON payload', { status: 400 })
  }

  await recordAndApplyPaymentEvent({ eventId, event })
  return new Response('ok')
}

recordAndApplyPaymentEvent 可以使用資料庫中 event_id 的唯一索引，但只有唯一約束還不夠。事件記錄和它的持久化結果——訂單狀態更新或 outbox 任務——必須原子提交。透過 merchant_order_id 或儲存的 StableOps Payment Order ID 找到內部訂單，並且只接受 DETECTED -> CONFIRMED -> FINALIZED 這類合法遷移；遲到的 payment.detected 不能把已經 finalized 的訂單倒退。簽名校驗必須使用原始 body；先解析再序列化 JSON 會改變簽名輸入。完整的驗籤、重試和重放行為見 Webhook 文件。

回滾不是異常分支，而是狀態機的一部分

payment.reverted 很少發生，但它不應該被當成“日誌裡看到了再處理”的異常分支。對於每個可能在 confirmed 前後產生樂觀效果的動作，都應預先定義補償：撤銷站內餘額、取消尚未執行的發貨任務、凍結後續服務，或者轉交人工稽核。

補償不等於立刻刪除所有業務記錄。更好的做法是保留原始支付事件、補償事件和操作者資訊，讓財務與客服能回答三個問題：當時為什麼認為付款有效、系統做過什麼、後來為什麼撤銷。這樣對帳時不會把鏈上的回滾誤判成普通的訂單取消。

還應區分“尚未履約”和“已經履約”。前者可以直接終止任務；後者要根據權益型別選擇衝正、補發付款連結或人工處理。即使產品承諾只在 finalized 後履約，也應訂閱並記錄 payment.reverted，因為它能暴露鏈資料、節點和訂單狀態之間的不一致。

上線前的檢查清單

支付頁能清楚展示“等待支付”“確認中”“支付完成”“支付失敗或已過期”，而不是把所有狀態都寫成成功。
不可逆履約只由 payment.finalized 觸發，並且該動作本身可以按訂單 ID 安全重試。
Webhook 先驗籤；事件記錄與狀態更新或 outbox 任務原子提交後，再返回 2xx。
合法遷移檢查會阻止遲到或重放的事件讓訂單狀態倒退。
payment.reverted、payment.expired 和重複投遞都有自動化測試或演練記錄。
訂單、支付事件、鏈上交易雜湊和 Webhook 投遞 ID 能相互關聯，客服可以從訂單直接定位問題。
失敗和死信有告警；修復端點後可以透過重放恢復處理，而不需要人工偽造支付成功。

把這套檢查放進發布流程，確認數就不再只是鏈基礎設施團隊的參數，而是一個可審計的產品承諾。

下一步

先為你的產品列出所有會因收款而觸發的動作，按“可撤銷”和“不可逆”分組，再把每一組對映到 confirmed 或 finalized。如果還沒有支付事件的端到端測試，從一次 payment.finalized 的冪等履約和一次 payment.reverted 的補償演練開始，通常能最快暴露狀態設計中的缺口。