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。 |
| 订单模式 | 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 时间戳（毫秒）。 |
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。 |
| 单目的地资金转出 | 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。 |
| 批量下发加密货币 | 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。 |
Webhook 事件示例
以下示例根据 Payment 规范中的字段定义构造，仅供参考。选填字段在实际 Webhook 推送中可能不存在。
payment.order.status.updated
payment.transaction.created
payment.payout.status.updated
提示
为了保证数据的绝对准确性并避免并发冲突，Webhook 消息体中不会包含实时余额变动和详细扣费信息。如果您存在以下使用场景，请参考下列提示说明：- 若需要根据 Webhook 通知及时更新余额，您可以：在接收到 Webhook 时，立即调用 List merchant balances 或 Get developer balances 接口获得准确的余额信息，再进行内部记账。
- 若需要及时知道 Webhook 所指交易引发的扣费信息，以便于关联交易和扣费进行对账，您可以：使用对应的查询交易信息接口和 Generate reports 获取扣费报表，来做数据的核对。
- 若需要及时知道 Webhook 所指交易引发的 Fee Station 余额的变动情况，保证后续不因 Fee Station 余额不足而影响业务，您可以：定期调用 List Fee Station token balance 查询 Fee Station 余额，并根据业务的消耗频率做内部报警策略，避免欠费影响正常业务运行。