退款接入

StableOps 記錄退款請求並核對鏈上結果，不保管商戶私鑰，也不替商戶簽名或廣播交易。退款是獨立記錄，原付款訂單仍保持 finalized，不要透過改寫原訂單狀態表示退款。

適用範圍與退款額度

• 僅對已 finalized、具有原始支付事件的訂單建立退款。
• 鏈、資產和來源地址沿用原付款：退款必須從原收款地址發出，不能隨意換鏈、換幣或改由另一個熱錢包傳送。
• 支援全額退款和部分退款。amount 是人類可讀的十進位制字串，精度不得超過該代幣的小數位數。
• 剩餘額度等於原訂單金額減去 requested、submitted、confirmed 退款金額之和。failed 與 canceled 不佔額度；失敗退款再次提交時會重新核算。

少付、多付、錯鏈、錯幣或過期後到帳沒有讓原訂單完成時，不能針對該訂單呼叫退款介面。按異常付款處理核實實際資金，再透過商戶自己的資金工具處理。

1. 核對付款與目標地址

先查詢原付款訂單及關聯交易，核實訂單、實際收款鏈、資產和金額。讓客戶明確確認退款鏈與目標地址，並將退款申請關聯到內部客服或審批記錄。

不要預設退到原交易的來源地址。 來源可能是交易所熱錢包、託管帳戶或合約地址，原路轉帳未必能記入客戶帳戶。商戶還需確認能控制原收款地址，併為退款交易準備對應鏈所需的手續費或資源。

2. 建立退款請求

在商戶伺服器端使用目前組織和環境的 API 金鑰呼叫建立非託管退款請求：

POST /v1/refunds
Authorization: Bearer sk_sandbox_...
Content-Type: application/json

{
  "payment_order_id": "替換為已完成的付款訂單標識",
  "amount": "5.00",
  "destination_address": "替換為客戶確認且符合原付款鏈格式的地址"
}

成功後儲存返回的 id、chain、asset、amount、source_address 和 destination_address。此時狀態為 requested，只是登記申請並佔用額度，沒有轉出資金。

建立請求不是按業務申請號自動去重的操作。同一個原訂單可以有多筆部分退款；重複建立可能佔用額外額度。商戶必須序列處理同一退款申請並持久化退款標識。網路超時後先查詢退款列表核對已有記錄，不要盲目重建立立。

3. 商戶錢包簽名並廣播

由有許可權的資金操作人員或受控錢包流程，按退款記錄指定的來源地址、目標地址、鏈、資產和精確金額簽名並廣播轉帳。不得把私鑰提交到 StableOps 或寫入應用日誌。

廣播後立即儲存交易雜湊。錢包或網路超時時先核查是否已廣播，不能直接再次轉帳。平台登記交易雜湊與錢包轉出資金是兩步獨立操作，商戶需要能從任一步中斷後恢復。

4. 登記交易雜湊

呼叫登記退款交易：

POST /v1/refunds/{id}/submit
Authorization: Bearer sk_sandbox_...
Content-Type: application/json

{
  "tx_hash": "替換為已廣播的退款交易雜湊"
}

狀態進入 submitted。同一退款仍為 submitted 時，重複登記同一個雜湊會返回現有記錄，不再發起轉帳；這不代表錢包廣播操作本身冪等。其他退款已登記過的交易雜湊不能複用。

5. 查詢與確認

透過查詢退款讀取結果：

submitted 不是退款完成。回執暫時缺失或節點無法確認結果時，記錄可能繼續等待，不應據此另付一筆。退款 confirmed 使用平台確認深度，不是對協議級最終性或零風險的承諾。

平台會產生 refund.requested、refund.submitted、refund.confirmed 和 refund.failed 事件。若使用這些事件驅動業務，仍須按 Webhook 指南驗籤、去重並查詢權威狀態；不要依賴取消事件，取消後讀取介面回應或查詢記錄。

取消與失敗恢復

取消請求只接受 requested 狀態。已在錢包廣播但尚未登記雜湊時，應先補登記，不能因為平台仍顯示 requested 就取消並重新退款。

failed 狀態允許再次登記交易雜湊，但必須先調查失敗原因和實際資金去向，確認是否需要新交易。平台會重新檢查可退款額度；期間已建立其他退款時，原請求可能已沒有足夠額度。不要把“平台核對失敗”直接等同於“鏈上沒有轉出任何資金”。

儲存內部審批記錄、退款標識、每次廣播的交易雜湊與處理結果，定期檢查長期 requested 或 submitted 的記錄。退款完成後更新自己的財務帳本與客戶通知，而不是修改原訂單的支付終態。