文档 / 集成

退款

退款即把款项转回给顾客：适用于订单取消、多付，或过期后的少付。可通过 API 或在后台提交退款申请。

由谁转出款项

取决于申请中的 executor 字段：

merchant：付款进入了您的钱包（常见情况）。Coinetic 不托管您的资金：由您自己向顾客转账，并登记交易哈希。
platform：付款进入了平台钱包。您只需发起退款申请；由 Coinetic 运营人员核验地址、审批并转出。

规则

只能以原支付资产退款。顾客用 TRON 上的 USDT 付款，就会收到 TRON 上的 USDT。不做兑换。
不超过已付金额，请查看账单的 refundable_amount。支持分次退款，每张账单最多 20 个未完成的申请。
地址必须属于原支付网络。按该网络的地址格式校验（EVM 使用 EIP-55 校验和）。不接受 Coinetic 自己的地址。
已支付的账单仍保持已支付状态。已退金额见 refunded_amount。
对未付清的账单执行退款，会永久关闭该账单，即使只是部分退款：账单变为 cancelled，之后的补付不再计入订单。提交申请前请先确认账单状态。

提交申请

POST/v1/refunds

HTTP

POST /v1/refunds
Idempotency-Key: refund-ORDER-1001-1
Content-Type: application/json

{"invoice_id":"inv_x7k2…","amount_minor":"10500000","address":"TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE","reason":"取消订单 ORDER-1001"}

字段	必填	说明
`invoice_id`	是	您商店的账单
`amount_minor`	是	以字符串表示的最小单位金额（6 位小数时 `"10500000"` = 10.5 USDT），或 `"full"`，表示全部可退金额
`address`	是	顾客在原支付网络上的地址
`reason`	否	退款原因，最多 500 个字符

从您的钱包退款

从您自己的钱包，以原支付资产和网络向顾客转出申请中的 amount（网络手续费由您承担）。
登记交易哈希：

HTTP

POST /v1/refunds/{id}/executed
Idempotency-Key: refund-exec-ORDER-1001-1
Content-Type: application/json

{"tx_hash":"0x5c50…","ack_status_change":false}

申请将进入 reported 状态。在 EVM 网络（Ethereum、BSC、Polygon、Base、Arbitrum）上，Coinetic 会自动在链上找到已确认的交易，将申请转为 sent，并发送 refund.sent Webhook。Bitcoin、Litecoin、TRON 和 Solana 暂不支持自动核验，申请会保持 reported 状态。

如需撤销，请调用 POST /v1/refunds/{id}/cancel 并注明原因：该金额将重新变为可退。

状态

状态	含义
`requested`	申请已受理
`approved`	已由运营人员批准（仅限 `executor: platform`）
`reported`	您已提交交易哈希，等待链上确认
`sent`	款项已转出，`tx_hash` 为链上交易
`rejected`	已拒绝或已撤销，原因见 `reject_reason`

拒绝不会通过 Webhook 通知，请定时检查未完成的申请：GET /v1/refunds?status=requested。

在沙盒中

POST /v1/refunds/{id}/simulate 会一次性走完整个流程：申请变为 sent 并带有测试用 tx_hash，同时发送 refund.sent。生产环境中没有此接口。