> ## 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. # 事件概述 Cobo Payments 通过 Webhook 事件通知您的系统。本页列出 Cobo Payments 提供的全部事件，并按支付业务分组。点击事件名称可查看该事件的触发条件、字段说明和示例。 ## 全部事件 事件分为两类： * **标准事件**：各支付业务的结果通知，按您使用的业务订阅。 * **高级事件**：提供底层链上交易的细节，例如确认数、链上交易手续费和区块信息。同一业务结果已由标准事件通知，除非您需要这些细节，否则无需订阅。
业务 事件 类型 通知什么
**充值** [`payment.topup.updated`](/payments/cn/guides/events/top-up#payment-topup-updated) **标准事件** 充值状态发生变更：已检测到、合规筛查中、需要处理、完成或失败。
[`payment.address.updated`](/payments/cn/guides/events/top-up#payment-address-updated) **标准事件** 付款方的充值地址被替换。Cobo 也会主动更换地址。
[`payment.transaction.created`](/payments/cn/guides/events/advanced#payment-transaction-created) 高级事件 充值地址收到一笔新的充值，附带链上交易细节。
[`payment.transaction.completed`](/payments/cn/guides/events/advanced#payment-transaction-completed) 高级事件 一笔充值通过合规筛查，附带链上交易细节。
[`payment.transaction.failed`](/payments/cn/guides/events/advanced#payment-transaction-failed) 高级事件 一笔充值失败或被拒绝（例如合规筛查未通过），附带链上交易细节。
**订单** [`payment.order.updated`](/payments/cn/guides/events/orders#payment-order-updated) **标准事件** 支付订单状态发生变更：待支付、处理中、已付清、少付或过期；某笔入金需要处理、失败，或在订单结束后到达时也会通知。
[`payment.order.status.updated`](/payments/cn/guides/events/advanced#payment-order-status-updated) 高级事件 支付订单状态发生变更，附带链上交易细节。
[`payment.transaction.late`](/payments/cn/guides/events/advanced#payment-transaction-late) 高级事件 订单进入终态后又收到一笔通过合规筛查的入金。
[`payment.transaction.completed`](/payments/cn/guides/events/advanced#payment-transaction-completed) 高级事件 订单的一笔入金通过合规筛查，附带链上交易细节。
[`payment.transaction.failed`](/payments/cn/guides/events/advanced#payment-transaction-failed) 高级事件 订单的一笔入金失败或被拒绝（例如合规筛查未通过），附带链上交易细节。
**意外入金** [`payment.transaction.external.created`](/payments/cn/guides/events/unexpected-deposits#payment-transaction-external-created) **标准事件** 检测到一笔意外入金（非当前订单/充值计划内的交易，或非支付服务支持的币种充币）。
[`payment.transaction.external.completed`](/payments/cn/guides/events/unexpected-deposits#payment-transaction-external-completed) **标准事件** 该笔意外入金通过合规筛查。
**退款** [`payment.refund.updated`](/payments/cn/guides/events/refunds#payment-refund-updated) **标准事件** 退款单状态发生变更：待执行、完成或失败。
[`payment.refund.status.updated`](/payments/cn/guides/events/advanced#payment-refund-status-updated) 高级事件 退款单状态发生变更，附带链上交易细节。
**资金转出** [`payment.payout.updated`](/payments/cn/guides/events/payouts#payment-payout-updated) **标准事件** 资金转出状态发生变更：已受理、准备资金、转出中、完成、部分完成、失败或被收款银行退回。
[`payment.payout.status.updated`](/payments/cn/guides/events/advanced#payment-payout-status-updated) 高级事件 资金转出状态发生变更，附带链上交易细节。
**法币提现** [`payment.bank_withdrawal.status.updated`](/payments/cn/guides/events/payouts#payment-bank_withdrawal-status-updated) **标准事件** 从您的虚拟账户提现法币到银行账户的状态变更。
**批量下发** [`payment.bulk_send.updated`](/payments/cn/guides/events/bulk-send#payment-bulk_send-updated) **标准事件** 批量下发批次状态发生变更：已创建、校验中、执行中、完成、部分完成或失败，附带金额和条目数量汇总。
[`payment.bulk_send.item.updated`](/payments/cn/guides/events/bulk-send#payment-bulk_send-item-updated) **标准事件** 批量下发条目状态发生变更：待执行、执行中、完成、失败或未执行。
[`payment.bulk_send.status.updated`](/payments/cn/guides/events/advanced#payment-bulk_send-status-updated) 高级事件 批量下发批次状态发生变更。
[`payment.bulk_send.item.status.updated`](/payments/cn/guides/events/advanced#payment-bulk_send-item-status-updated) 高级事件 批量下发条目进入终态：`Completed`、`Failed` 或 `NotExecuted`。
**余额** [`payment.account.balance.updated`](/payments/cn/guides/events/balances#payment-account-balance-updated) **标准事件** 某账户某币种的可用余额变动，给出变动前后的余额和变动来源。
## 事件结构 所有 Webhook 消息共用同一个外层结构。`event_id` 是事件的唯一标识，同一条事件重投时不变，可用于去重。 外层的 `created_timestamp` 是**这条事件的创建时间，单位毫秒**，重投时不变，不能用于判断事件先后（参见[事件顺序](#事件顺序)）。`data` 里的 `created_timestamp` 与 `updated_timestamp` 是**业务对象自己的创建与最近更新时间，单位秒**。 外层的 `status`（`Success`、`Retrying`、`Failed`）以及重试时才出现的 `next_retry_timestamp`、`retries_left` 描述的是这条消息的投递情况，与业务无关，处理时可以忽略。 ```json theme={null} { "event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b2f", "url": "https://example.com/webhook", "created_timestamp": 1701396866000, "type": "payment.topup.updated", "data": { "data_type": "PaymentTopUpUpdate", ... "created_timestamp": 1701396800, "updated_timestamp": 1701396865 }, "status": "Success" } ``` | `type` | `data.data_type` | 业务对象 ID | | - | - | - | | `payment.topup.updated` | `PaymentTopUpUpdate` | `transaction_id` | | `payment.order.updated` | `PaymentOrderUpdate` | `order_id` | | `payment.refund.updated` | `PaymentRefundUpdate` | `refund_id` | | `payment.payout.updated` | `PaymentPayoutUpdate` | `payout_id` | | `payment.bulk_send.updated` | `PaymentBulkSendUpdate` | `bulk_send_id` | | `payment.bulk_send.item.updated` | `PaymentBulkSendItemUpdate` | `bulk_send_item_id` | ## 所有事件通用的规则 ### 事件顺序 Cobo 不保证事件按发生的顺序送达。例如，一笔资金转出依次经过 `Pending`、`Preparing`、`Transferring`、`Completed`，但如果其中某条事件投递失败后重试，您可能先收到 `Completed`，再收到 `Transferring`。 请确保您的处理逻辑不依赖事件的到达顺序。需要确认某个对象的最新状态时，可调用对应的查询接口，例如 [Get pay-in order information](/payments/en/api-references/payment/get-pay-in-order-information)、[Get refund order information](/payments/en/api-references/payment/get-refund-order-information)、[Get payout information](/payments/en/api-references/payment/get-payout-information) 或 [Get bulk send information](/payments/en/api-references/payment/get-bulk-send-information)。 ### 空值 字段表中的字段始终出现在 payload 里，不适用时为 `null`，空数组为 `[]`。标注「选填」或「仅……时出现」的字段除外。 ### 失败原因 可能汇报失败的事件会携带一个 `failed_reason` 对象。 ```json theme={null} "failed_reason": { "code": "transaction.rejected_by_policy", "message": "..." } ``` `code` 是受控枚举，请根据它决定如何处理。`message` 面向运营人员，措辞可能调整，因此可以展示，但不要用于匹配。 每个业务页面会列出该对象上可能出现的 code，并按需要采取的处理方式分组：[充值](/payments/cn/guides/events/top-up#失败原因)、[订单](/payments/cn/guides/events/orders#失败原因)、[退款](/payments/cn/guides/events/refunds#失败原因)、[资金转出及提现](/payments/cn/guides/events/payouts#失败原因)、[批量下发](/payments/cn/guides/events/bulk-send#批次的失败原因)。 ### 金额 **除特殊说明外，金额固定 2 位小数（多余位数截断，不四舍五入），去掉尾零**（`100.00` 输出 `100`）。 | 结构 | 示例 | 用在哪 | | - | - | - | | 资产金额 | `{ "amount": "100", "token_id": "ETH_USDC", "chain_id": "ETH" }` | 绝大多数金额字段。 | | 资产或法币金额 | `{ "amount_type": "Crypto", "amount": "300", "token_id": "TRON_USDT", "chain_id": "TRON" }` `{ "amount_type": "Fiat", "amount": "497.5", "currency": "USD" }` | 可能是加密货币也可能是法币的字段，例如 `actual_payout_amounts` 的元素。用 `amount_type` 判断是哪一种。 | | 佣金 | `{ "fee_amount": "2.5" }` | Cobo 收取的佣金，**单位为美元**。佣金从 Fee Station 扣，余额是美元口径。 | 字段名为复数的（例如 `requested_amounts`）是数组，可能跨多种 token；单数字段是单个对象，只涉及一种资产。不要跨资产相加。数组按 `token_id` 分组，同一种币在两条链上是两项。 ## 设置接收端 设置 Webhook Endpoint 并订阅事件的步骤，请参阅[处理 Webhook 事件](/payments/cn/developer-tools/webhook#处理-webhook-事件)。