> ## 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.
# 事件与状态
本文介绍收款、退款和资金转出过程中涉及到的所有 Webhook 事件以及状态变更流程。
## Webhook 事件
### **1. 入账相关**
| 功能场景 | 事件名称 | 触发条件 | 事件内容 |
| :--- | :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 订单模式 | `payment.order.status.updated` | 支付订单状态发生变更，会触发的节点包括：
- `Pending`：此状态通知仅限于通过支付链接成功创建订单时触发。
- `Completed`：在订单有效期内收到全额付款。
- `Expired`：订单有效期内没有已完成的充币交易，或者订单已被取消。
- `Underpaid`：订单有效期内存在已完成的充币交易，但实收金额少于应付金额。 | 该负载包含以下字段：
- `order_id`（必填）：订单 ID。
- `merchant_id`（选填）：商户 ID。
- `merchant_order_code`（选填）：商户分配的唯一参考编码。
- `psp_order_code`（必填）：开发者用于标识该订单的唯一参考编码。
- `pricing_currency`（选填）：订单的计价货币。
- `pricing_amount`（选填）：订单的基础金额（不含开发者手续费）。
- `fee_amount`（必填）：该订单的开发者手续费。
- `payable_currency`（选填）：用于付款的加密货币 ID。
- `chain_id`（必填）：区块链网络 ID。
- `payable_amount`（必填）：该订单需支付的加密货币金额。
- `exchange_rate`（必填）：`payable_currency` 与 `pricing_currency` 之间的汇率。
- `amount_tolerance`（选填）：允许的金额偏差。
- `receive_address`（必填）：收款钱包地址。
- `status`（必填）：当前订单状态，可能的值：`Pending`、`Processing`、`Completed`、`Expired`、`Underpaid`。
- `received_token_amount`（必填）：该订单已收到的加密货币总金额。
- `expired_at`（选填）：过期时间，Unix 时间戳（秒）。
- `created_timestamp`（选填）：创建时间，Unix 时间戳（秒）。
- `updated_timestamp`（选填）：最后更新时间，Unix 时间戳（秒）。
- `transactions`（选填）：与该订单关联的支付交易数组。
完整字段说明请参考 [Get pay-in order information](/payments/en/api-references/payment/get-pay-in-order-information)。 |
| 订单模式 | `payment.transaction.late` | 在支付订单已处于终态（`Underpaid`、`Expired` 或 `Completed`）后又收到一笔通过合规筛查的充币交易。 | 该负载包含[交易负载字段](#交易负载字段)部分的所有基础字段，以及以下 Payment 专属字段：
- `acquiring_type`（必填）：收款类型，值为 `Order`（仅限订单模式）。
- `order_id`（选填）：支付订单 ID。
- `psp_order_code`（选填）：开发者用于标识该订单的唯一参考编码。 |
| 充值模式 | `payment.transaction.created` | 充值地址检测到有新的充币交易。 | 该负载包含[交易负载字段](#交易负载字段)部分的所有基础字段，以及以下 Payment 专属字段：
- `acquiring_type`（必填）：收款类型，值为 `TopUp`（仅限充值模式）。
- `payer_id`（选填）：Cobo 分配的用于跟踪和识别付款人的唯一标识符。
- `custom_payer_id`（选填）：开发者系统中用于跟踪和识别付款人的唯一标识符。 |
| 充值模式 | `payment.address.updated` | payer 充值地址被更换。 | 该负载包含以下字段：
- `custom_payer_id`：您系统内的付款人唯一标识。
- `payer_id`：Cobo 分配的付款人唯一标识。
- `chain`：地址所属链。
- `previous_address`：更换前地址。
- `updated_address`：更换后地址。 |
| 订单模式 | `payment.transaction.completed` | 订单有效期内收到的每笔交易，通过合规筛查后，资金已成功入账并计入实收金额。 | 该负载包含[交易负载字段](#交易负载字段)部分的所有基础字段，以及以下 Payment 专属字段：
- `acquiring_type`（必填）：收款类型，值为 `Order`。
- `order_id`（选填）：支付订单 ID。
- `psp_order_code`（选填）：开发者用于标识该订单的唯一参考编码。 |
| 充值模式 | `payment.transaction.completed` | 充币交易通过合规筛查，资金已成功入账并计入实收金额。 | 该负载包含[交易负载字段](#交易负载字段)部分的所有基础字段，以及以下 Payment 专属字段：
- `acquiring_type`（必填）：收款类型，值为 `TopUp`。
- `payer_id`（选填）：Cobo 分配的用于跟踪和识别付款人的唯一标识符。
- `custom_payer_id`（选填）：开发者系统中用于跟踪和识别付款人的唯一标识符。 |
| 意外入账 | `payment.transaction.external.created` | 检测到非预期充币交易（包括：非当前订单/充值计划内的交易，或非支付服务支持的币种充币）。 | 该负载包含[交易负载字段](#交易负载字段)部分的所有基础字段。 |
| 意外入账 | `payment.transaction.external.completed` | 非预期充币交易已通过合规筛查并成功入账，资金已计入开发者余额。 | 该负载包含[交易负载字段](#交易负载字段)部分的所有基础字段。 |
| 入账检查 | `payment.transaction.failed` | 入账交易合规筛查不通过。 | 该负载包含[交易负载字段](#交易负载字段)部分的所有基础字段，以及以下 Payment 专属字段：
- `acquiring_type`（必填）：收款类型，`Order` 表示订单模式，`TopUp` 表示充值模式。
- `order_id`（选填）：支付订单 ID。
- `psp_order_code`（选填）：开发者用于标识该订单的唯一参考编码。
- `payer_id`（选填）：Cobo 分配的用于跟踪和识别付款人的唯一标识符。
- `custom_payer_id`（选填）：开发者系统中用于跟踪和识别付款人的唯一标识符。 |
### 交易负载字段
下表列出所有 `payment.transaction.*` 事件负载中包含的基础字段。在一些场景下，部分字段可能不会返回。
| 字段 | 类型 | 是否必填 | 说明 |
| :--------------------- | :-------------- | :--- | :------------------------- |
| `transaction_id` | string (UUID) | 是 | 交易 ID。 |
| `cobo_id` | string | 否 | 用于追踪交易的 Cobo ID。 |
| `request_id` | string | 否 | 用于追踪交易请求的请求 ID。 |
| `wallet_id` | string | 是 | 充币交易中为目标钱包 ID；其他类型为源钱包 ID。 |
| `type` | string | 否 | 交易类型。 |
| `status` | string | 是 | 交易状态。 |
| `sub_status` | string | 否 | 交易子状态。 |
| `failed_reason` | string | 否 | 交易失败原因（仅适用于审批和签名失败）。 |
| `chain_id` | string | 否 | 链 ID。 |
| `token_id` | string | 否 | 代币 ID。 |
| `asset_id` | string | 否 | 资产 ID（仅限交易所钱包）。 |
| `transaction_hash` | string | 否 | 交易哈希。 |
| `source` | object | 是 | 交易来源。 |
| `destination` | object | 是 | 交易目标。 |
| `result` | object | 否 | 交易结果。 |
| `fee` | object | 否 | 交易手续费。 |
| `initiator` | string | 否 | 交易发起者。 |
| `initiator_type` | string | 是 | 发起者类型。 |
| `confirmed_num` | integer | 否 | 已收到的确认数。 |
| `confirming_threshold` | integer | 否 | 所需最低确认数。 |
| `block_info` | object | 否 | 区块信息。 |
| `raw_tx_info` | object | 否 | 原始交易信息。 |
| `replacement` | object | 否 | 替换交易信息。 |
| `category` | array | 否 | 自定义交易分类。 |
| `description` | string | 否 | 交易描述。 |
| `is_loop` | boolean | 否 | 是否为 Cobo Loop 转账。 |
| `cobo_category` | array | 否 | Cobo 定义的交易分类。 |
| `extra` | array | 否 | 结构化的业务专属附加信息。 |
| `fueling_info` | object | 否 | 加油信息。 |
| `created_timestamp` | integer (int64) | 是 | 创建时间，Unix 时间戳（毫秒）。 |
| `updated_timestamp` | integer (int64) | 是 | 最后更新时间，Unix 时间戳（毫秒）。 |
每个交易事件还包含事件内容列中列出的 Payment 专属字段。
### **2. 资金转出相关**
| 功能场景 | 事件名称 | 触发条件 | 事件内容 |
| :------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 退款 | `payment.refund.status.updated` | 退款单状态发生变更，会触发的节点包括：
- `Pending`：此状态通知仅限于通过退款链接成功创建退款单时触发。
- `Completed`：所有退款交易均已完成。
- `PartiallyCompleted`：部分退款交易已完成，部分退款交易失败。
- `Failed`：所有退款交易均失败。 | 该负载包含以下字段：
- `refund_id`（必填）：退款订单 ID。
- `request_id`（选填）：创建退款时您提供的请求 ID。
- `order_id`（选填）：该退款对应的收款订单 ID。
- `merchant_id`（选填）：商户 ID。
- `token_id`（必填）：用于退款的加密货币 ID。
- `chain_id`（必填）：区块链网络 ID。
- `amount`（必填）：该退款需退还的加密货币金额。
- `to_address`（必填）：收款钱包地址。
- `status`（必填）：当前退款状态，可能的值：`AddressPending`、`AddressSubmitted`、`Pending`、`Processing`、`Completed`、`PartiallyCompleted`、`Failed`、`PendingConfirmation`。
- `refund_type`（选填）：资金来源，可能的值：`Merchant`、`Psp`。
- `created_timestamp`（必填）：创建时间，Unix 时间戳（秒）。
- `updated_timestamp`（必填）：最后更新时间，Unix 时间戳（秒）。
- `initiator`（选填）：退款请求发起者。
- `transactions`（选填）：与该退款关联的支付交易数组。
- `charge_merchant_fee`（选填）：是否向商户收取开发者手续费。
- `merchant_fee_amount`（选填）：向商户收取的开发者手续费金额。
- `merchant_fee_token_id`（选填）：开发者手续费使用的加密货币 ID。
- `commission_fee`（选填）：佣金费用详情。
完整字段说明请参考 [Get refund order information](/payments/en/api-references/payment/get-refund-order-information)。 |
| 单目的地资金转出 | `payment.payout.status.updated` | 资金转出请求状态变更，会触发的节点包括：
- `Completed`：所有资金转出已完成。
- `PartiallyCompleted`：部分资金转出已完成，部分资金转出失败。
- `Failed`：所有资金转出均失败。 | 该负载包含以下字段：
- `payout_id`（必填）：资金转出 ID。
- `request_id`（必填）：创建资金转出时您提供的请求 ID。
- `payout_channel`（必填）：转出渠道，可能的值：`Crypto`、`OffRamp`。
- `source_account`（选填）：转出来源账户。
- `payout_items`（选填）：转出条目数组。
- `recipient_info`（选填）：收款人信息。
- `initiator`（选填）：资金转出请求发起者。
- `actual_payout_amount`（选填）：实际到账金额。
- `commission_fees`（选填）：该笔转出的佣金费用数组。
- `remark`（选填）：备注信息。
- `status`（必填）：当前转出状态，可能的值：`Pending`、`Preparing`、`Transferring`、`Completed`、`PartiallyCompleted`、`Failed`、`RejectedByBank`。
- `created_timestamp`（必填）：创建时间，Unix 时间戳（秒）。
- `updated_timestamp`（必填）：最后更新时间，Unix 时间戳（秒）。
- `transactions`（选填）：与该笔转出关联的支付交易数组。
完整字段说明请参考 [Get payout information](/payments/en/api-references/payment/get-payout-information)。 |
| 批量下发加密货币 | `payment.bulk_send.status.updated` | 批量下发请求状态变更，会触发的节点包括：
- `Completed`：所有下发已完成。
- `PartiallyCompleted`：部分下发已完成，部分下发失败。
- `Failed`：所有下发均失败。 | 该负载包含以下字段：
- `bulk_send_id`（必填）：批量下发 ID。
- `request_id`（选填）：创建批量下发时您提供的请求 ID。
- `source_account`（必填）：转出来源账户。
- `description`（选填）：整批下发的描述。
- `execution_mode`（必填）：执行模式。
- `status`（必填）：当前批量下发状态。
- `created_timestamp`（必填）：创建时间，Unix 时间戳（秒）。
- `updated_timestamp`（必填）：最后更新时间，Unix 时间戳（秒）。
完整字段说明请参考 [Get bulk send information](/payments/en/api-references/payment/get-bulk-send-information)。 |
| 账户余额 | `payment.account.balance.updated` | 支付账户某币种的可用余额发生变动时触发。 | 该负载包含以下字段：
- `source_account`（必填）：余额变动的来源账户。商户账户为商户 ID；开发者账户为 `developer`。
- `source_id`（必填）：余额变动的来源 ID。
- `source_type`（必填）：余额变动的来源类型（例如 `OrderIn`、`Payout`、`RefundOut`、`BulkSend`）。
- `token_id`（必填）：币种 ID。
- `amount`（必填）/ `amount_raw`（必填）：余额变动金额，分别为保留两位小数和按币种精度表示。
- `balance_before` / `balance_before_raw`（必填）：变动前的账户余额。
- `balance_after` / `balance_after_raw`（必填）：变动后的账户余额。
- `flow_direction`（必填）：余额变动方向，可能的值：`in`、`out`。
- `update_time`（必填）：余额更新时间，Unix 时间戳（秒）。 |
### **3. 结算网络相关**
| 功能场景 | 事件名称 | 触发条件 | 事件内容 |
| :----------------- | :------------------------------------------------- | :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| Settlement Network | `payment.transaction.settlement_network.created` | 结算网络交易创建时触发。 | 该负载包含[交易负载字段](#交易负载字段)部分的基础字段。详情请参考 [结算网络](/payments/cn/guides/settlement-network) 指南。 |
| Settlement Network | `payment.transaction.settlement_network.completed` | 结算网络交易完成时触发。交易完成后，结算资金会以 `SettlementNetwork` 这一 `source_type` 反映到您的 Payment 账户余额中。 | 该负载包含[交易负载字段](#交易负载字段)部分的基础字段。详情请参考 [结算网络](/payments/cn/guides/settlement-network) 指南。 |
## Webhook 事件示例
以下示例根据 Payment 规范中的字段定义构造，仅供参考。选填字段在实际 Webhook 推送中可能不存在。
### payment.order.status.updated
```json theme={null}
{
"event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b1f",
"url": "https://example.com/webhook",
"created_timestamp": 1701396866000,
"type": "payment.order.status.updated",
"data": {
"data_type": "PaymentOrder",
"order_id": "O20250304-M1001-1001",
"merchant_id": "1001",
"psp_order_code": "P20240201001",
"pricing_currency": "USD",
"pricing_amount": "100.00",
"fee_amount": "2.00",
"payable_currency": "ETH_USDT",
"chain_id": "ETH",
"payable_amount": "103.03",
"exchange_rate": "0.99",
"receive_address": "0x1234567890abcdef1234567890abcdef12345678",
"status": "Completed",
"received_token_amount": "103.0305",
"created_timestamp": 1744689600,
"updated_timestamp": 1744689600
},
"status": "Success"
}
```
### payment.transaction.created
```json theme={null}
{
"event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b2f",
"url": "https://example.com/webhook",
"created_timestamp": 1701396866000,
"type": "payment.transaction.created",
"data": {
"data_type": "PaymentTransaction",
"transaction_id": "aff0e1cb-15b2-4e1f-9b9d-a9133715986f",
"wallet_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "Submitted",
"chain_id": "ETH",
"token_id": "ETH_USDT",
"transaction_hash": "239861be9a4afe080c359b7fe4a1d035945ec46256b1a0f44d1267c71de8ec28",
"source": { "source_type": "DepositFromAddress" },
"destination": { "destination_type": "DepositToAddress" },
"initiator_type": "API",
"created_timestamp": 1701396866000,
"updated_timestamp": 1701396866000,
"acquiring_type": "TopUp",
"payer_id": "P20250619T0310056d7aa",
"custom_payer_id": "user_abc_10001"
},
"status": "Success"
}
```
### payment.payout.status.updated
```json theme={null}
{
"event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b3f",
"url": "https://example.com/webhook",
"created_timestamp": 1701396866000,
"type": "payment.payout.status.updated",
"data": {
"data_type": "PaymentPayout",
"payout_id": "123e457-e89b-12d3-a456-426614174004",
"request_id": "123e457-e89b-12d3-a456-426614174004",
"payout_channel": "Crypto",
"source_account": "M1001",
"status": "Completed",
"created_timestamp": 1744689600,
"updated_timestamp": 1744689600
},
"status": "Success"
}
```
### payment.account.balance.updated
```json theme={null}
{
"event_id": "9a3f1c2b-7d8e-4f0a-9b2c-5d6e7f8a9b0c",
"url": "https://example.com/webhook",
"created_timestamp": 1701396866000,
"type": "payment.account.balance.updated",
"data": {
"data_type": "PaymentAccountBalanceUpdate",
"source_account": "M1001",
"source_id": "O202503041234567890",
"source_type": "OrderIn",
"token_id": "Tron_USDT",
"amount": "20.00",
"amount_raw": "20",
"balance_before": "100.00",
"balance_before_raw": "100",
"balance_after": "120.00",
"balance_after_raw": "120",
"flow_direction": "in",
"update_time": 1701396866
},
"status": "Success"
}
```
***
## 提示
为了保证数据的绝对准确性并避免并发冲突，Webhook 消息体中不会包含实时余额变动和详细扣费信息。如果您存在以下使用场景，请参考下列提示说明：
* 若需要根据 Webhook 通知及时更新余额，您可以：在接收到 Webhook 时，立即调用 [List merchant balances](/payments/en/api-references/payment/list-merchant-balances) 或 [Get developer balances](/payments/en/api-references/payment/get-developer-balance) 接口获得准确的余额信息，再进行内部记账。
* 若需要及时知道 Webhook 所指交易引发的扣费信息，以便于关联交易和扣费进行对账，您可以：使用对应的查询交易信息接口和 [Generate reports](/payments/en/api-references/payment/generate-reports) 获取扣费报表，来做数据的核对。
* 若需要及时知道 Webhook 所指交易引发的 Fee Station 余额的变动情况，保证后续不因 Fee Station 余额不足而影响业务，您可以：定期调用 [List Fee Station token balance](https://www.cobo.com/developers/v2/api-references/feestation/list-fee-station-token-balances) 查询 Fee Station 余额，并根据业务的消耗频率做内部报警策略，避免欠费影响正常业务运行。