资金转出及提现

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

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

请先阅读事件概述了解外层结构、去重方式以及所有事件通用的规则。

本页的事件

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

`payment.payout.updated`

资金转出的主事件。

事件触发条件

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

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

触发条件	`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`	金额，格式见金额。
`requested_amounts.token_id`	`string`	币种 ID。
`requested_amounts.chain_id`	`string`	链 ID。
`failed_amounts`	`array`	`requested_amounts` 中未成功转出的部分。到终态时，成功转出的金额等于两者之差。
`failed_amounts.amount`	`string`	金额，格式见金额。
`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`	金额，格式见金额。
`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`	金额，格式见金额。
`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 中拒绝了这笔转账。	到该应用查看原因，然后重新创建转出。
`transaction.rejected_by_compliance`	Cobo 的合规检查拒绝了这笔转账。	不要重试，联系 Cobo。
`transaction.failed`	原因无法归类。	联系 Cobo 并提供 `payout_id`。

示例事件

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

转出请求已受理

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

{
  "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 已完成转账，不表示收款方平台已经入账。

{
  "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 的金额另建一笔新的转出，不要重发已成功的部分。本例请求转出两种币种，其中一种在转出交易上失败，因此对象级和条目级的原因都有。

{
  "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 为空。

{
  "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。

{
  "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 创建。

`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 时间戳（秒）。

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

完整说明请参见 Get bank withdrawal information。

高级事件

需要资金转出的链上交易细节时，可订阅高级事件 payment.payout.status.updated，参见高级事件。

概览

初始配置

收款

资金管理

索引信息

本页的事件

`payment.payout.updated`

事件触发条件

事件内容

失败原因

示例事件

转出请求已受理

转出完成

转出部分完成

转出失败

Off-Ramp 转出被银行拒绝

`payment.bank_withdrawal.status.updated`

高级事件

​本页的事件

​payment.payout.updated

​事件触发条件

​事件内容

​失败原因

​示例事件

​转出请求已受理

​转出完成

​转出部分完成

​转出失败

​Off-Ramp 转出被银行拒绝

​payment.bank_withdrawal.status.updated

​高级事件

本页的事件

`payment.payout.updated`

事件触发条件

事件内容

失败原因

示例事件

转出请求已受理

转出完成

转出部分完成

转出失败

Off-Ramp 转出被银行拒绝

`payment.bank_withdrawal.status.updated`

高级事件