如何不用真錢測試加密貨幣支付：沙盒、測試網與水龍頭

加密貨幣支付測試不能只證明“錢包顯示了交易雜湊”。你的應用還要建立正確的訂單、展示鏈與資產明確的精確付款指令、檢測轉帳、等待確認與最終完成、接收非同步 Webhook，並確保每項業務副作用只執行一次。如果全部使用主網測試，每個錯誤都會損失真錢；如果全部替換成模擬資料，又會掩蓋最需要發現的接入故障。

實用的解決方法是把測試分成三層：

1. 用本地測試驗證驗籤、事件去重、過期處理和狀態順序等確定性規則；
2. 用沙盒環境與公共測試網驗證真實的錢包、遠端過程呼叫節點、掃描器、確認與 Webhook 鏈路；
3. 上線前核對沙盒與生產環境的邊界，不要用一筆小額真實轉帳代替缺失的測試。

最短的端到端路徑，是在 StableOps 試驗場使用 Base Sepolia USDC。測試網 USDC 沒有真實金融價值，但錢包交易以及訂單從 created 到 finalized 的生命週期都真實發生在測試網上。

為什麼加密貨幣支付需要三層測試

鏈上支付有三個特點，使它不同於普通的同步介面測試。

不要讓一個緩慢的瀏覽器測試同時承擔三類職責。合理的測試套件應包含大量快速本地測試、少量真實測試網流程，以及啟用生產環境前的一份簡短設定核對表。

每一層應該證明什麼

第一層：確定性的本地測試

業務正確性不應依賴水龍頭或公共遠端過程呼叫節點。本地單元測試和整合測試至少要證明應用能夠：

• 使用未經修改的原始請求正文驗籤；
• 拒絕缺少簽名、簽名過期或簽名錯誤的請求；
• 依靠資料庫唯一約束寫入 X-Event-Id；
• 同一事件到達兩次時，只接受一次狀態變化、只履約一次；
• 較舊事件遲到時，不會讓業務狀態倒退；
• 只允許 payment.finalized 觸發不可逆履約；
• 把 payment.expired 與 payment.reverted 分別送入明確的異常分支；
• 使用相同冪等鍵重試建單時，不會產生第二筆業務債權。

這一層應使用模擬時鐘。你可以在幾毫秒內把訂單時間推進到過期，也可以隨時使用帶有效簽名的 payment.reverted 測試資料。公共測試網很難快速、穩定地復現這些情況，因此它們更適合留在本地測試中。

第二層：執行在真實測試網上的沙盒環境

沙盒測試應該驗證原生程式碼無法覆蓋的接縫：

• 所選錢包能切換到預期測試網；
• 代幣合約或鑄幣地址確實是 StableOps 在該網路上支援的資產；
• 錢包把返回的 order.amount 精確傳送到客戶所選付款指令的地址；
• 鏈掃描器能發現並匹配這筆轉帳；
• 無需人工推送狀態，訂單便能依次進入 detected、confirmed 與 finalized；
• 帶簽名的 Webhook 投遞能到達公開的測試端點。

StableOps 會按組織、環境、鏈、地址、資產以及最小單位精確金額隔離掃描和匹配。因此，沙盒訂單使用沒有價值的測試資產，卻能覆蓋與生產環境相同的支付語義。

第三層：上線前的邊界核對

不要把主網當成缺失的一層測試。最後一步應該核對生產環境中有意不同的設定：介面金鑰、收款地址、Webhook 端點與金鑰、開放鏈、監控方式和營運責任人。程式碼路徑在此之前就應透過前兩層測試。

最短端到端測試：Base Sepolia USDC

你需要一枚 StableOps 沙盒介面金鑰、一個以太坊虛擬機器瀏覽器錢包，以及一個與真實資金隔離的測試錢包地址。開發過程不要複用資金錢包。

1. 給測試錢包領取資產

在 Base Sepolia 上領取兩種測試資產：

• 用於支付金額的測試網 USDC；
• 用於支付燃料費的 Base Sepolia ETH。

兩項餘額必須位於同一個測試網。主網 ETH 不能支付 Base Sepolia 燃料費，主網 USDC 更不能傳送到試驗場給出的付款指令。水龍頭可用性和領取限制經常變化，因此應使用持續維護的測試網 USDC 與 USDT 水龍頭清單，不要從舊教程複製外部連結。Circle 明確說明測試網 USDC 沒有金融價值；即便如此，簽名與授權仍然是真實操作，所以錢包仍應保持隔離。

2. 在試驗場建立沙盒訂單

開啟試驗場，貼上以 sk_sandbox_… 開頭的金鑰。如果沙盒地址池為空，保持“自動匯入沙盒收款地址”開啟。選擇 Base Sepolia · USDC，輸入一個小額金額並建立訂單。

付款前先記錄以下返回值：

試驗場可能為這次沙盒演示匯入一個確定性銷燬地址。沒有人持有其私鑰，所以傳送到該地址的測試幣會有意變得無法取回。對沒有價值的水龍頭代幣而言這不構成損失，也再次說明絕不能透過試驗場傳送主網資產。

3. 讓錢包傳送精確付款

連線測試錢包，讓試驗場提交 USDC 轉帳。簽名前在錢包確認頁逐項核對：

• 網路：Base Sepolia；
• 資產：受支援的 Base Sepolia USDC 合約；
• 收款人：訂單返回的付款指令地址；
• 金額：返回的 order.amount，而不是你記憶中剛才輸入的數字。

交易雜湊只表示錢包已經廣播交易。它是有用的排查證據，但不是履約憑據。

4. 觀察生命週期到達最終完成

試驗場會輪詢訂單並展示每次狀態變化：

created -> detected -> confirmed -> finalized

detected 表示掃描器已經匹配一筆鏈上轉帳；confirmed 表示已經達到該鏈的確認閾值；finalized 表示 StableOps 已達到設定的最終確認深度，也是生產環境觸發不可逆履約的推薦時機。測試網出塊與公共遠端過程呼叫節點建立索引的速度會波動，因此測試應斷言狀態順序和一個寬裕的超時時間，不能斷言固定秒數。

如果需要獨立核對終態，可以在建單後執行下面的指令碼。它使用目前介面軟體開發工具包，並會在訂單過期、取消、回滾或等待超時時以失敗狀態退出：

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

const apiKey = process.env.STABLEOPS_API_KEY
const paymentOrderId = process.argv[2]

if (!apiKey?.startsWith('sk_sandbox_')) {
  throw new Error('請使用沙盒介面金鑰')
}
if (!paymentOrderId) throw new Error('請傳入付款訂單號')

const client = new StableOps({ apiKey })
const deadline = Date.now() + 10 * 60 * 1000
let previousStatus: string | undefined

while (Date.now() < deadline) {
  const order = await client.paymentOrders.retrieve(paymentOrderId)

  if (order.status !== previousStatus) {
    console.log(new Date().toISOString(), order.status)
    previousStatus = order.status
  }

  if (order.status === 'finalized') process.exit(0)
  if (['reverted', 'expired', 'canceled'].includes(order.status)) {
    throw new Error(`訂單終態為 ${order.status}`)
  }

  await new Promise((resolve) => setTimeout(resolve, 3_000))
}

throw new Error('等待最終完成超時')

將其儲存為 wait-for-payment.ts，安裝 @stableops/api-sdk 與 tsx 後執行：

STABLEOPS_API_KEY=sk_sandbox_... npx tsx wait-for-payment.ts po_...

輪詢適合用作測試斷言與恢復路徑。實際應用仍應使用帶簽名的 Webhook 取得低延遲事件流。

單獨測試 Webhook 路徑

把沙盒 Webhook 端點指向一個公開的 HTTPS 測試地址，訂閱 payment.detected、payment.confirmed、payment.finalized、payment.reverted 與 payment.expired，然後完整執行一次試驗場流程。

每次投遞都應保留：

• 用於驗籤的原始請求正文；
• 作為事件級去重鍵的 X-Event-Id；
• 作為單次投遞診斷鍵的 X-Delivery-Id；
• 事件型別、付款訂單號、回應碼和處理結果。

處理器成功接收事件後，再重放一次相同投遞。第二次請求仍應返回成功回應，但不得再次履約或寫入帳目。另外，本地還要用不同順序輸入同一組事件測試資料。真實網路不會保證每個消費者都按照自己期望的順序觀察到全部非同步結果。

完整的持久事件收件箱與發件箱模式，見穩定幣支付 Webhook：如何避免重複履約。

可直接複製的加密貨幣支付測試矩陣

可以把下表作為最小發布測試集。只有真實測試網能提供額外資訊時，才讓用例依賴測試網；其餘用例都應保持確定性。

不要試圖操縱公共測試網來製造鏈重組，也不要呼叫不存在的“設定訂單狀態”介面。StableOps 不提供人工推送訂單狀態的路徑：回滾分支用測試資料驗證，正常鏈驅動生命週期則交給測試網驗證。

讓沙盒與生產環境不可能混淆

環境隔離應該單獨設定釋出門檻，因為一段正確的測試如果使用了錯誤憑據，仍可能移動真實資金。

• 持續整合、預覽部署、本地終端和瀏覽器演示只包含 sk_sandbox_… 金鑰。
• 除明確命名的生產部署外，應用啟動時拒絕 sk_live_… 金鑰。
• 沙盒與生產環境使用不同的 Webhook 端點，或使用明確隔離的事件收件箱名稱空間和金鑰。
• 測試網收款地址只設定在沙盒環境，主網收款地址只設定在生產環境。
• 日誌與對帳記錄包含環境、組織、merchantOrderId 和付款訂單號。
• 測試資料不包含真實客戶資料、私鑰、助記詞或生產 Webhook 金鑰。
• 第一筆客戶付款前，生產監控已經覆蓋投遞失敗、死信、訂單過期與地址池容量。
• 上線核對使用目前文件驗證支援的鏈與代幣合約，絕不復制測試網值。

環境由介面金鑰本身決定；不存在把沙盒金鑰變成生產金鑰的請求頭。應該把上線視為使用生產憑據重建立立經過核對的設定，而不是把沙盒訂單遷移到生產環境。

常見問題

沒有任何測試網代幣，也能測試加密貨幣支付嗎？

驗籤、冪等、Webhook 順序、過期邏輯和回滾處理都可以只用本地測試資料。要執行真實的錢包到掃描器端到端測試，仍需要測試網穩定幣和該網路的原生燃料代幣。兩者都能透過水龍頭領取，且沒有金融價值。

加密貨幣支付沙盒只是模擬區塊鏈嗎？

StableOps 試驗場不是這樣。建單使用沙盒憑據，但錢包會在公共測試網上廣播真實轉帳；掃描、匹配、確認觀察和最終完成都走真實鏈路，所以遠端過程呼叫延遲和出塊時間會波動。

應該如何測試鏈重組與 payment.reverted？

在本地整合測試中使用帶簽名的事件測試資料觸發回滾路徑，並驗證 payment.finalized 之前絕不啟動不可逆履約。鏈重組非常少見，也無法在公共測試網上安全控制，因此等待真實重組不是可行的釋出測試。生命週期邊界見穩定幣支付確認數。

先跑通一筆，再自動驗證邊界

從試驗場開始，使用持續維護的水龍頭清單給隔離錢包領取測試資產，並觀察一筆 Base Sepolia USDC 訂單進入 finalized。然後把上面的測試矩陣轉成一組本地測試資料和一個小型定時沙盒冒煙測試。全部透過後，再按照快速開始把相同的訂單與 Webhook 契約接入應用，同時繼續讓生產憑據遠離測試路徑。