付款單

瞭解 StableOps 付款單如何繫結準確金額、穩定幣資產、區塊鏈和收款地址，以及訂單從建立、過期、檢測、確認到最終完成或回退的完整資源模型與生命週期。掌握支付指令、狀態欄位、過期規則和事件語義，確保業務只在正確狀態下履約、記帳或觸發異常處理。

付款單（payment order）表示「請客戶向某條鏈上的指定地址打一筆具體金額」。 StableOps 負責分配地址、監聽鏈上、追蹤確認數、並在每次狀態變化時發出簽名 Webhook。

生命週期

created -> detected -> confirmed -> finalized
   |          |            |
expired   reverted     reverted
   |
canceled

created：地址已分配，等待入帳。
detected：鏈上看到匹配的轉帳。
confirmed：達到該鏈的確認閾值。
finalized：達到 finality 閾值，履約最穩的節點。
expired：超過過期時間仍未匹配到轉帳。
canceled：仍處於 created（尚未檢測到任何入帳）時被人工取消。
reverted：receipt 失敗，或 block hash 不再與儲存的事件匹配。

建立訂單

const order = await client.paymentOrders.create(
  {
    merchantOrderId: 'order_123',
    amount: '10.00',
    amountMode: 'exact',
    acceptedAssets: [
      { chain: 'base', asset: 'USDC' },
      { chain: 'ethereum', asset: 'USDC' },
    ],
    expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
    metadata: { customerId: 'cus_123' },
  },
  { idempotencyKey: 'order_123:create-payment-order' },
)

console.log(order.paymentInstructions)
// [
//   { chain: 'base', asset: 'USDC', address: '0x...' },
//   { chain: 'ethereum', asset: 'USDC', address: '0x...' },
// ]

amountMode 控制金額匹配模式。省略時預設為 exact：

exact（預設）：客戶必須支付指定的精確金額。使用共享（shared）地址時需自行確保同一地址上的不同訂單金額不衝突，否則 StableOps 無法區分入帳歸屬。
auto：伺服器端在共享地址上遇到金額衝突時自動微調訂單金額（在基準金額上小幅上調），保證每筆訂單金額唯一。原始請求金額存於 requestedAmount，實際應付金額以返回的 amount 為準。

amount 是資產單位的十進位制字串。鏈上事件攜帶最小單位的整數字符串，StableOps 在內部按代幣的 decimals 轉換後再做匹配。

地址分配

單地址（single）模式：每個未結訂單獨佔一個可用地址，直到 finalized / reverted / expired / canceled。共享（shared）模式：一個地址可同時供多個未結訂單使用，按鏈 + 資產 + 組織 + 環境 + 金額精確匹配。

建立訂單時，StableOps 會按 acceptedAssets 裡的每條 (鏈, 資產) 組合各預分配一個可用候選地址，寫進 paymentInstructions。訂單進入終態（finalized / reverted / expired / canceled）時，仍未被使用的候選地址會被釋放回池子。

取消訂單

只有 created 狀態的訂單可以呼叫 cancel。一旦訂單進入 detected / confirmed / finalized 就不能再取消。已經最終完成的付款必須使用獨立的退款流程，不能改寫原訂單。取消會把訂單上仍佔用的候選地址釋放回 available。

冪等與唯一性

Idempotency-Key 控制請求重放；merchantOrderId 是獨立的業務引用，在組織 + 環境內必須唯一。用同一個 merchantOrderId 配新的 idempotency key 再開單會得到衝突，而不是上一次的回應。

Webhook

訂單相關的事件型別：

payment_order.created
payment.detected
payment.confirmed
payment.finalized
payment.expired
payment.reverted
payment_order.canceled

除非業務明確接受 payment.confirmed 後還可能發生回滾的風險，否則請在 payment.finalized 完成履約。

完整事件清單與 payload 見 Webhooks。