退款接入

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 的记录。退款完成后更新自己的财务账本与客户通知，而不是修改原订单的支付终态。