> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/payments/llms.txt
> Use this file to discover all available pages before exploring further.

# 退款

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

## 本页的事件

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

## `payment.refund.updated`

退款的主事件。

### 事件触发条件

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

![退款状态变化](https://mintcdn.com/mcpnow/mlWrRJ_rKxcpt9Zx/payments/cn/images/payments/events/refunds-status.svg?fit=max\&auto=format\&n=mlWrRJ_rKxcpt9Zx\&q=85\&s=4f54c75bff4fcaeb028a44bd4e97b208)

上图为主要的状态变化路径，绿色框为终态。事件可能不按顺序送达，参见[事件顺序](/payments/cn/guides/events/overview#事件顺序)。

| 触发条件 | `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` | 金额，格式见[金额](/payments/cn/guides/events/overview#金额)。 |
| `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](https://manuals.cobo.com/cn/apps/screening/introduction) 中拒绝了这笔转账。 | 到该应用查看原因，然后重新创建退款。 |
| `transaction.rejected_by_compliance` | Cobo 的合规检查拒绝了这笔转账。 | 不要重试，联系 Cobo。 |
| `transaction.failed` | 原因无法归类。 | 联系 Cobo 并提供 `refund_id`。 |

### 示例事件

以下示例只展示 `data` 对象。外层结构所有事件都一样，参见[事件结构](/payments/cn/guides/events/overview#事件结构)。

#### 退款单已创建

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

```json theme={null}
{
  "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
}
```

#### 退款完成

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

```json theme={null}
{
  "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` 为空。

```json theme={null}
{
  "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 充值后重新创建退款。

```json theme={null}
{
  "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`，参见[高级事件](/payments/cn/guides/events/advanced#payment-refund-status-updated)。