> ## 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.

# 资金转出及提现

本页的事件跟踪单笔资金转出或转账请求，包括：

* 加密货币转账
* Off-Ramp 对接
* 从您的某个虚拟账户提现法币到银行账户

请先阅读[事件概述](/payments/cn/guides/events/overview)了解外层结构、去重方式以及所有事件通用的规则。

## 本页的事件

| 事件 | 通知什么 | 类型 |
| - | - | - |
| [`payment.payout.updated`](#payment-payout-updated) | 资金转出状态发生变更：已受理、准备资金、转出中、完成、部分完成、失败或被收款银行退回。 | **标准事件** |
| [`payment.bank_withdrawal.status.updated`](#payment-bank_withdrawal-status-updated) | 从您的某个虚拟账户提现法币到银行账户的状态变更。 | **标准事件** |

## `payment.payout.updated`

资金转出的主事件。

### 事件触发条件

**该笔资金转出的 `status` 每变化一次发一条事件。**

![资金转出状态变化](https://mintcdn.com/mcpnow/mlWrRJ_rKxcpt9Zx/payments/cn/images/payments/events/payouts-status.svg?fit=max\&auto=format\&n=mlWrRJ_rKxcpt9Zx\&q=85\&s=c52d6f3afd0e0ece6b7035a699aa1e51)

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

| 触发条件 | `status` | 您该做什么 |
| - | - | - |
| 转出请求被受理 | `Pending` | 记录本次转出，不要重复提交。 |
| 开始准备资金（归集、跨链兑换、扣佣金） | `Preparing` | 等待。 |
| 开始执行转出交易 | `Transferring` | 等待。 |
| 全部转出成功 | `Completed`（终态） | 在您的系统中将该笔转出标记为已完成。 |
| 有一部分没有成功 | `PartiallyCompleted`（终态） | 按 `failed_amounts` 的金额另建一笔转出补发，不要重复支付已成功的部分。 |
| 全部失败，包括在准备资金阶段（归集、跨链兑换、扣佣金）失败 | `Failed`（终态） | 读取 `failed_reason.code` 并处理。 |
| 收款银行退回这笔 Off-Ramp 转账 | `RejectedByBank` | 联系 Cobo 处理，并等待后续事件。 ⚠️ **`RejectedByBank` 不是终态。** 联系 Cobo 处理后，这笔转出会回到 `Transferring`，并可能最终 `Completed`。 |

### 事件内容

| 字段 | 类型 | 说明 |
| - | - | - |
| `data_type` | `string` | 固定为 `PaymentPayoutUpdate`。 |
| `payout_id` | `string` | 转出 ID。 |
| `request_id` | `string` | 您创建本次转出时提供的请求 ID。 |
| `source_account` | `string` | 资金来源账户：商户账户为商户 ID，开发者账户为 `developer`。 |
| `status` | `string` | 当前状态，含义见[事件触发条件](#事件触发条件)： • `Pending` • `Preparing` • `Transferring` • `Completed` • `PartiallyCompleted` • `Failed` • `RejectedByBank` |
| `requested_target` | `object` | 收款目标。不含完整账号等敏感信息，需要时用 `bank_account_id` 查询。 |
| `requested_target.target_type` | `string` | 收款目标类型： • `Address`：加密货币地址。 • `BankAccount`：银行账户（Off-Ramp）。 |
| `requested_target.address` | `string` | 收款地址。仅 `target_type` 为 `Address` 时出现。 |
| `requested_target.chain_id` | `string` | 链 ID。仅 `target_type` 为 `Address` 时出现。 |
| `requested_target.bank_account_id` | `string` | 银行账户 ID。仅 `target_type` 为 `BankAccount` 时出现。 |
| `requested_target.account_alias` | `string` | 银行账户别名。仅 `target_type` 为 `BankAccount` 时出现。 |
| `requested_target.bank_name` | `string` | 银行名称。仅 `target_type` 为 `BankAccount` 时出现。 |
| `requested_target.currency` | `string` | 账户币种，例如 `USD`。仅 `target_type` 为 `BankAccount` 时出现。 |
| `initiator` | `string` | 转出发起方，通常是 API key。 |
| `remark` | `string` | 您创建转出时填写的备注，未填写时为 `null`。 |
| `requested_amounts` | `array` | 您请求转出的金额，按币种分组，创建时确定。 |
| `requested_amounts.amount` | `string` | 金额，格式见[金额](/payments/cn/guides/events/overview#金额)。 |
| `requested_amounts.token_id` | `string` | 币种 ID。 |
| `requested_amounts.chain_id` | `string` | 链 ID。 |
| `failed_amounts` | `array` | `requested_amounts` 中未成功转出的部分。到终态时，成功转出的金额等于两者之差。 |
| `failed_amounts.amount` | `string` | 金额，格式见[金额](/payments/cn/guides/events/overview#金额)。 |
| `failed_amounts.token_id` | `string` | 币种 ID。 |
| `failed_amounts.chain_id` | `string` | 链 ID。 |
| `actual_payout_amounts` | `array` | 收款方实际收到的金额，**仅在 `status` 为 `Completed` 或 `PartiallyCompleted` 时有值**，其余情况为 `[]`。加密货币转出按实际转出的币种每种一项；Off-Ramp 只有一项。 • ⚠️ **该值不一定等于 `requested_amounts` 减去 `failed_amounts`**：经过跨链兑换或 Off-Ramp 对接后，收款方收到的币种可能与您转出的不同；且跨链兑换和 Off-Ramp 对接的手续费会从您请求转出的金额中扣除，收款方实收因此少于 `requested_amounts`。 |
| `actual_payout_amounts.amount_type` | `string` | 金额类型，先读它再读其余字段： • `Crypto`：加密货币。 • `Fiat`：法币（Off-Ramp 打到银行账户）。 |
| `actual_payout_amounts.amount` | `string` | 金额，格式见[金额](/payments/cn/guides/events/overview#金额)。 |
| `actual_payout_amounts.token_id` | `string` | 币种 ID。仅 `amount_type` 为 `Crypto` 时出现。 |
| `actual_payout_amounts.chain_id` | `string` | 链 ID。仅 `amount_type` 为 `Crypto` 时出现。 |
| `actual_payout_amounts.currency` | `string` | 法币币种，例如 `USD`。仅 `amount_type` 为 `Fiat` 时出现。 |
| `commission_fee` | `object` | Cobo 收取的佣金，未产生时为 `null`。 |
| `commission_fee.fee_amount` | `string` | 佣金金额，**单位为美元**。佣金从 Fee Station 扣，余额按美元计。跨多个币种转出时，此处为各币种佣金的合计。 |
| `transactions` | `array` | 该笔转出的全部转出交易。 |
| `transactions.transaction_id` | `string` | 该笔转出交易在 Cobo 系统中的 ID。 |
| `transactions.amount` | `object` | 该笔交易实际转出的金额。经过跨链兑换后，币种可能与 `requested_amounts` 中的币种不同。 |
| `transactions.amount.amount` | `string` | 金额，格式见[金额](/payments/cn/guides/events/overview#金额)。 |
| `transactions.amount.token_id` | `string` | 币种 ID。 |
| `transactions.amount.chain_id` | `string` | 链 ID。 |
| `transactions.tx_hash` | `string` | 链上交易哈希，广播前为 `null`。 |
| `transactions.result` | `string` | 该笔交易的结果： • `Completed`：已成功转出。 • `Failed`：未成功。 |
| `transactions.failed_reason` | `object` | `result` 为 `Failed` 时有值，其余情况为 `null`。 |
| `transactions.failed_reason.code` | `string` | 失败原因代码。取值见[失败原因](#失败原因)。 |
| `transactions.failed_reason.message` | `string` | 失败原因。 |
| `failed_reason` | `object` | `status` 为 `Failed`、`RejectedByBank` 或 `PartiallyCompleted` 时有值，其余情况为 `null`。 |
| `failed_reason.code` | `string` | 失败原因代码。取值见[失败原因](#失败原因)。 |
| `failed_reason.message` | `string` | 失败原因。 |
| `created_timestamp` | `integer` | 该次转出的创建时间，Unix 时间戳（秒）。 |
| `updated_timestamp` | `integer` | 该次转出最近一次状态更新时间，Unix 时间戳（秒）。 |

### 失败原因

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

| `code` | 发生了什么 | 怎么处理 |
| - | - | - |
| `payment.payout_fee_charge_failed` | Fee Station 余额不足。 | 充值后重新创建转出。 |
| `payment.payout_fee_station_not_configured` | 未配置 Fee Station。 | 联系 Cobo，配置完成后重新创建转出。 |
| `payment.payout_fee_charge_failed_unknown` | 手续费因其他原因扣收失败。 | 联系 Cobo 并提供 `payout_id`。 |
| `payment.payout_sweep_failed` | 转出前的资金归集失败。 | 重新创建转出。 |
| `payment.payout_bridge_failed` | 全部跨链交易失败，资产无法兑换。 | 联系 Cobo 确认该币种对可以兑换，然后重新创建转出。 |
| `payment.payout_transactions_failed` | 全部转出交易均失败。 | 查看 `transactions` 中各条目的 `failed_reason`，处理后重新创建转出。 |
| `payment.payout_rejected_by_bank` | 收款银行退回了这笔转账，仅 Off-Ramp 会出现。**这不是终态。** | 联系 Cobo 处理，并等待后续事件。 |
| `payment.payout_partially_failed` | 这笔转出有一部分未能完成。`failed_amounts` 为未转出的金额。 | 查看 `transactions` 中失败条目的 `failed_reason`，处理后为这部分金额另建一笔转出。 |
| `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 并提供 `payout_id`。 |

### 示例事件

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

#### 转出请求已受理

记录本次转出，不要重复提交。`requested_target` 与您创建转出时提交的内容一致，请核对。

```json theme={null}
{
  "data_type": "PaymentPayoutUpdate",
  "payout_id": "payout_001",
  "request_id": "request_payout_001",
  "source_account": "developer",
  "status": "Pending",
  "requested_amounts": [
    { "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" }
  ],
  "failed_amounts": [],
  "requested_target": {
    "target_type": "Address",
    "address": "0xrecipient001",
    "chain_id": "ETH"
  },
  "transactions": [],
  "actual_payout_amounts": [],
  "initiator": "api_key_abc123",
  "commission_fee": null,
  "remark": "September vendor settlement",
  "failed_reason": null,
  "created_timestamp": 1744700000,
  "updated_timestamp": 1744700000
}
```

#### 转出完成

在您的系统中将该笔转出标记为已完成。这表示 Cobo 已完成转账，**不表示**收款方平台已经入账。

```json theme={null}
{
  "data_type": "PaymentPayoutUpdate",
  "payout_id": "payout_001",
  "request_id": "request_payout_001",
  "source_account": "developer",
  "status": "Completed",
  "requested_amounts": [
    { "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" }
  ],
  "failed_amounts": [],
  "requested_target": {
    "target_type": "Address",
    "address": "0xrecipient001",
    "chain_id": "ETH"
  },
  "transactions": [
    {
      "transaction_id": "9a8b7c6d-0001-4e5f-8a9b-000000000001",
      "amount": { "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "tx_hash": "0xpayout001",
      "result": "Completed",
      "failed_reason": null
    }
  ],
  "actual_payout_amounts": [
    { "amount_type": "Crypto", "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" }
  ],
  "initiator": "api_key_abc123",
  "commission_fee": { "fee_amount": "1" },
  "remark": "September vendor settlement",
  "failed_reason": null,
  "created_timestamp": 1744700000,
  "updated_timestamp": 1744700600
}
```

#### 转出部分完成

按 `failed_amounts` 的金额**另建一笔新的转出**，不要重发已成功的部分。

本例请求转出两种币种，其中一种在转出交易上失败，因此对象级和条目级的原因都有。

```json theme={null}
{
  "data_type": "PaymentPayoutUpdate",
  "payout_id": "payout_002",
  "request_id": "request_payout_002",
  "source_account": "developer",
  "status": "PartiallyCompleted",
  "requested_amounts": [
    { "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" },
    { "amount": "300", "token_id": "ETH_USDT", "chain_id": "ETH" }
  ],
  "failed_amounts": [
    { "amount": "300", "token_id": "ETH_USDT", "chain_id": "ETH" }
  ],
  "requested_target": {
    "target_type": "Address",
    "address": "0xrecipient002",
    "chain_id": "ETH"
  },
  "transactions": [
    {
      "transaction_id": "9a8b7c6d-0002-4e5f-8a9b-000000000001",
      "amount": { "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "tx_hash": "0xpayout002a",
      "result": "Completed",
      "failed_reason": null
    },
    {
      "transaction_id": "9a8b7c6d-0002-4e5f-8a9b-000000000002",
      "amount": { "amount": "300", "token_id": "ETH_USDT", "chain_id": "ETH" },
      "tx_hash": null,
      "result": "Failed",
      "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."
      }
    }
  ],
  "actual_payout_amounts": [
    { "amount_type": "Crypto", "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" }
  ],
  "initiator": "api_key_abc123",
  "commission_fee": { "fee_amount": "1" },
  "remark": "September vendor settlement",
  "failed_reason": {
    "code": "payment.payout_partially_failed",
    "message": "Part of this payout could not be completed. Check failed_amounts for the amount affected, then contact Cobo support."
  },
  "created_timestamp": 1744701000,
  "updated_timestamp": 1744701600
}
```

#### 转出失败

⚠️ 转出项也可能在任何转出交易产生之前就失败。本例在资金归集过程中失败，因此 `failed_amounts` 有金额，但 `transactions` 为空。

```json theme={null}
{
  "data_type": "PaymentPayoutUpdate",
  "payout_id": "payout_003",
  "request_id": "request_payout_003",
  "source_account": "developer",
  "status": "Failed",
  "requested_amounts": [
    { "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" }
  ],
  "failed_amounts": [
    { "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" }
  ],
  "requested_target": {
    "target_type": "Address",
    "address": "0xrecipient003",
    "chain_id": "ETH"
  },
  "transactions": [],
  "actual_payout_amounts": [],
  "initiator": "api_key_abc123",
  "commission_fee": null,
  "remark": null,
  "failed_reason": {
    "code": "payment.payout_sweep_failed",
    "message": "Cannot prepare payout funds: sweep transaction failed."
  },
  "created_timestamp": 1744702000,
  "updated_timestamp": 1744702200
}
```

#### Off-Ramp 转出被银行拒绝

**这不是终态。** 链上那一段已经完成（`transactions` 里的条目是 `Completed`），是收款银行退回了法币入账，所以 `failed_amounts` 为空。联系 Cobo 处理，并等待该笔转出的后续事件：重试成功时，您会先收到一条 `Transferring`，再收到 `Completed`。

```json theme={null}
{
  "data_type": "PaymentPayoutUpdate",
  "payout_id": "payout_004",
  "request_id": "request_payout_004",
  "source_account": "developer",
  "status": "RejectedByBank",
  "requested_amounts": [
    { "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" }
  ],
  "failed_amounts": [],
  "requested_target": {
    "target_type": "BankAccount",
    "bank_account_id": "ba_20260901_0007",
    "account_alias": "Vendor A operating account",
    "bank_name": "Example Bank",
    "currency": "USD"
  },
  "transactions": [
    {
      "transaction_id": "9a8b7c6d-0004-4e5f-8a9b-000000000001",
      "amount": { "amount": "500", "token_id": "ETH_USDC", "chain_id": "ETH" },
      "tx_hash": "0xpayout004",
      "result": "Completed",
      "failed_reason": null
    }
  ],
  "actual_payout_amounts": [],
  "initiator": "api_key_abc123",
  "commission_fee": { "fee_amount": "1" },
  "remark": null,
  "failed_reason": {
    "code": "payment.payout_rejected_by_bank",
    "message": "The receiving bank rejected this payout. Check the recipient's bank account details with them before resending — resending unchanged will most likely be rejected again."
  },
  "created_timestamp": 1744703000,
  "updated_timestamp": 1744703800
}
```

## `payment.bank_withdrawal.status.updated`

银行提现到达 `Completed` 或 `Failed` 时触发；`Pending` 和 `Processing` 不发事件。银行提现把法币从您的某个虚拟账户转出到目标银行账户，通过 [Create bank withdrawal](/payments/en/api-references/payment/create-bank-withdrawal) 创建。

| `status` | 含义 |
| - | - |
| `Pending` | 银行提现已创建，等待处理。 |
| `Processing` | 银行提现处理中。 |
| `Completed` | 资金已离开虚拟账户。 |
| `Failed` | 银行提现失败，原因见 `failed_reason`。 |

**事件内容：** `data` 对象的 `data_type` 为 `PaymentBankWithdrawal`，并包含：

* `bank_withdrawal_id`（必填）—— Cobo 生成的银行提现 ID。
* `request_id`（必填）—— 您创建银行提现时提供的请求 ID。
* `source_bank_account_id`（必填）—— 来源银行账户 ID，必须是虚拟账户（标记为 `VA`）。
* `target_bank_account_id`（必填）—— 接收本次提现的目标银行账户 ID。
* `source_bank_account`（必填）—— 来源银行账户的完整信息。
* `target_bank_account`（必填）—— 目标银行账户的完整信息。
* `currency`（必填）—— 银行提现的法币币种，例如 `USD`。
* `amount`（必填）—— 银行提现金额，以该币种展示单位的十进制字符串表示，例如 `100.00`。
* `bank_tx_fee`（选填）—— 本次银行提现收取的银行交易手续费。
* `status`（必填）—— 当前状态，取值为 `Pending`、`Processing`、`Completed`、`Failed` 之一。
* `remark`（选填）—— 银行提现备注。
* `failed_reason`（选填，字符串）—— 银行提现失败的原因文本，没有 `code`，仅当 `status` 为 `Failed` 时有值。
* `timeline`（必填）—— 银行提现的状态时间线。每一项包含一个 `status` 和进入该状态的 `timestamp`，Unix 时间戳（秒）。
* `created_timestamp`（必填）—— 创建时间，Unix 时间戳（秒）。

> [!NOTE]
>
> 银行提现的 payload 不携带 `updated_timestamp`。要确定它何时进入当前状态，请读取 `timeline` 的最后一项。

完整说明请参见 [Get bank withdrawal information](/payments/en/api-references/payment/get-bank-withdrawal-by-id)。

## 高级事件

需要资金转出的链上交易细节时，可订阅高级事件 `payment.payout.status.updated`，参见[高级事件](/payments/cn/guides/events/advanced#payment-payout-status-updated)。