退款 - Cobo Payments

本页的事件跟踪一笔退款单从创建到完成的全过程。请先阅读事件概述了解外层结构、去重方式以及所有事件通用的规则。

本页的事件

事件	通知什么	类型
`payment.refund.updated`	退款单状态发生变更：待执行、完成或失败。	标准事件

`payment.refund.updated`

退款的主事件。

事件触发条件

这笔退款单的 status 每变化一次发一条事件。

上图为主要的状态变化路径，绿色框为终态。事件可能不按顺序送达，参见事件顺序。

触发条件	`status`	您该做什么
退款单进入待执行——通过退款链接创建，或您直接调用创建退款接口	`Pending`	记录该退款单并等待。
退款完成	`Completed`（终态）	对账，并在您的系统中将该退款标记为已完成。
退款失败，未退还任何资金	`Failed`（终态）	读取 `failed_reason.code` 并处理。

事件内容

字段	类型	说明
`data_type`	`string`	固定为 `PaymentRefundUpdate`。
`refund_id`	`string`	退款单 ID。
`order_id`	`string`	本次退款对应的收款订单。
`merchant_id`	`string`	退款归属商户时为该商户的 ID，否则为 `null`。
`status`	`string`	退款单当前状态，事件中只会出现： • `Pending` • `Completed` • `Failed`
`request_id`	`string`	您创建退款时提供的请求 ID。
`to_address`	`string`	退款的收款地址。
`requested_amount`	`object`	请求退还的金额，对应创建退款时传入的 `payable_amount`。
`requested_amount.amount`	`string`	金额，格式见金额。
`requested_amount.token_id`	`string`	币种 ID。
`requested_amount.chain_id`	`string`	链 ID。
`tx_hash`	`string`	退款转账的链上哈希。尚未广播时为 `null`；失败时为 `null` 表示从未上链，有值表示已上链但失败。
`refund_type`	`string`	退款资金来源： • `Merchant`：商户余额。 • `Psp`：开发者余额。
`initiator`	`string`	退款发起方，通常是 API key。
`commission_fee`	`object`	Cobo 收取的佣金，未产生时为 `null`。
`commission_fee.fee_amount`	`string`	佣金金额，单位为美元。佣金从 Fee Station 扣，余额按美元计。
`failed_reason`	`object`	`status` 为 `Failed` 时有值，其余情况为 `null`。
`failed_reason.code`	`string`	失败原因代码。取值见失败原因。
`failed_reason.message`	`string`	失败原因。
`created_timestamp`	`integer`	该退款单的创建时间，Unix 时间戳（秒）。
`updated_timestamp`	`integer`	该退款单最近一次状态更新时间，Unix 时间戳（秒）。

失败原因

请根据 failed_reason.code 决定如何处理。

`code`	发生了什么	怎么处理
`payment.refund_fee_charge_failed`	Fee Station 余额不足。	充值后重新创建退款。
`payment.refund_fee_station_not_configured`	未配置 Fee Station。	联系 Cobo，配置完成后重新创建退款。
`payment.refund_fee_charge_failed_unknown`	手续费因其他原因扣收失败。	联系 Cobo 并提供 `refund_id`。
`payment.refund_sweep_failed`	退款前的资金归集失败。	重新创建退款。
`payment.refund_transactions_failed`	全部退款交易均失败。	重新创建退款。
`transaction.rejected_by_policy`	这笔转账命中了您自己配置的交易策略。	在 Cobo Portal 中调整该策略，然后重新创建退款。
`transaction.rejected_by_approval`	这笔转账在您组织的审批环节被拒绝——审批人拒绝，或您的回调服务器拒绝。	向对方确认原因，然后重新创建退款。
`transaction.rejected_by_signer`	这笔转账在签名环节被拒绝——co-signer 拒绝签名。	向 co-signer 确认原因，然后重新创建退款。
`transaction.rejected_by_screening_app`	您的合规团队在 Screening App 中拒绝了这笔转账。	到该应用查看原因，然后重新创建退款。
`transaction.rejected_by_compliance`	Cobo 的合规检查拒绝了这笔转账。	不要重试，联系 Cobo。
`transaction.failed`	原因无法归类。	联系 Cobo 并提供 `refund_id`。

示例事件

以下示例只展示 data 对象。外层结构所有事件都一样，参见事件结构。

退款单已创建

记录并等待。收到终态事件前，不要重复提交同一笔退款。

{
  "data_type": "PaymentRefundUpdate",
  "refund_id": "refund_001",
  "order_id": "order_001",
  "merchant_id": "M1001",
  "request_id": "request_refund_001",
  "to_address": "0x9876543210abcdef1234567890abcdef12345678",
  "status": "Pending",
  "requested_amount": { "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "tx_hash": null,
  "refund_type": "Merchant",
  "initiator": "api_key_abc123",
  "commission_fee": null,
  "failed_reason": null,
  "created_timestamp": 1744690400,
  "updated_timestamp": 1744690400
}

退款完成

对账，并在您的系统中将该退款标记为已完成。

{
  "data_type": "PaymentRefundUpdate",
  "refund_id": "refund_001",
  "order_id": "order_001",
  "merchant_id": "M1001",
  "request_id": "request_refund_001",
  "to_address": "0x9876543210abcdef1234567890abcdef12345678",
  "status": "Completed",
  "requested_amount": { "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "tx_hash": "0xrefund001",
  "refund_type": "Merchant",
  "initiator": "api_key_abc123",
  "commission_fee": { "fee_amount": "0.5" },
  "failed_reason": null,
  "created_timestamp": 1744690400,
  "updated_timestamp": 1744690500
}

退款失败

未退还任何资金。 本例转账从未上链，因此 tx_hash 为空。

{
  "data_type": "PaymentRefundUpdate",
  "refund_id": "refund_002",
  "order_id": "order_001",
  "merchant_id": "M1001",
  "request_id": "request_refund_002",
  "to_address": "0x9876543210abcdef1234567890abcdef12345678",
  "status": "Failed",
  "requested_amount": { "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "tx_hash": null,
  "refund_type": "Merchant",
  "initiator": "api_key_abc123",
  "commission_fee": { "fee_amount": "0" },
  "failed_reason": {
    "code": "transaction.rejected_by_policy",
    "message": "This transaction was rejected by one of your transaction policies. Please update the applicable policy in Cobo Portal before resubmitting."
  },
  "created_timestamp": 1744690600,
  "updated_timestamp": 1744690700
}

退款在转账之前就失败

手续费无法扣收。向 Fee Station 充值后重新创建退款。

{
  "data_type": "PaymentRefundUpdate",
  "refund_id": "refund_003",
  "order_id": "order_001",
  "merchant_id": "M1001",
  "request_id": "request_refund_003",
  "to_address": "0x9876543210abcdef1234567890abcdef12345678",
  "status": "Failed",
  "requested_amount": { "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" },
  "tx_hash": null,
  "refund_type": "Merchant",
  "initiator": "api_key_abc123",
  "commission_fee": null,
  "failed_reason": {
    "code": "payment.refund_fee_charge_failed",
    "message": "Cannot charge refund fee: Fee Station balance is insufficient. Please add funds to Fee Station and try again."
  },
  "created_timestamp": 1744690800,
  "updated_timestamp": 1744690900
}

高级事件

需要退款的链上交易细节时，可订阅高级事件 payment.refund.status.updated，参见高级事件。

概览

初始配置

收款

资金管理

索引信息

退款

本页的事件

`payment.refund.updated`

事件触发条件

事件内容

失败原因

示例事件

退款单已创建

退款完成

退款失败

退款在转账之前就失败

高级事件

​本页的事件

​payment.refund.updated

​事件触发条件

​事件内容

​失败原因

​示例事件

​退款单已创建

​退款完成

​退款失败

​退款在转账之前就失败

​高级事件

本页的事件

`payment.refund.updated`

事件触发条件

事件内容

失败原因

示例事件

退款单已创建

退款完成

退款失败

退款在转账之前就失败

高级事件