事件与状态

​

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（选填）— 与该订单关联的支付交易数组。

​

payment.transaction.late

• acquiring_type（必填）— 收款类型，值为 Order（仅限订单模式）。
• order_id（选填）— 支付订单 ID。
• psp_order_code（选填）— 开发者用于标识该订单的唯一参考编码。

​

payment.transaction.created

• acquiring_type（必填）— 收款类型，值为 TopUp（仅限充值模式）。
• payer_id（选填）— Cobo 分配的用于跟踪和识别付款人的唯一标识符。
• custom_payer_id（选填）— 开发者系统中用于跟踪和识别付款人的唯一标识符。

​

payment.address.updated

• custom_payer_id — 您系统内的付款人唯一标识。
• payer_id — Cobo 分配的付款人唯一标识。
• chain — 地址所属链。
• previous_address — 更换前地址。
• updated_address — 更换后地址。

​

payment.transaction.completed

• 订单模式：订单有效期内收到的每笔交易，通过合规筛查后，资金成功入账并计入实收金额。
• 充值模式：充币交易通过合规筛查后，资金成功入账并计入实收金额。

• 订单模式：acquiring_type（必填，值为 Order）、order_id（选填）、psp_order_code（选填）。
• 充值模式：acquiring_type（必填，值为 TopUp）、payer_id（选填）、custom_payer_id（选填）。

​

payment.transaction.external.created

​

payment.transaction.external.completed

​

payment.transaction.failed

• acquiring_type（必填）— 收款类型，Order 表示订单模式，TopUp 表示充值模式。
• order_id（选填）— 支付订单 ID。
• psp_order_code（选填）— 开发者用于标识该订单的唯一参考编码。
• payer_id（选填）— Cobo 分配的用于跟踪和识别付款人的唯一标识符。
• custom_payer_id（选填）— 开发者系统中用于跟踪和识别付款人的唯一标识符。

​

2. 资金转出相关

​

payment.refund.status.updated

• Pending：此状态通知仅限于通过退款链接成功创建退款单时触发。
• Completed：所有退款交易均已完成。
• 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、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（选填）— 佣金费用详情。

​

payment.payout.status.updated

• Completed：所有资金转出已完成。
• PartiallyCompleted：部分资金转出已完成，部分资金转出失败。
• Failed：所有资金转出均失败。
• RejectedByBank：收款银行拒绝了该笔 Off-Ramp 资金转出。

• 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（选填）— 与该笔转出关联的支付交易数组。

​

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

​

payment.bulk_send.item.status.updated

• bulk_send_item_id（必填）— 批量下发项目 ID。
• bulk_send_id（必填）— 该项目所属的批量下发 ID。
• request_id（选填）— 批量下发批次的请求 ID。
• source_account（必填）— 批量下发批次的来源账户 ID。
• token_id（必填）— 下发给收款人的加密货币 ID。
• receiving_address（必填）— 收款人的加密货币地址。
• amount（必填）— 下发给收款人的加密货币金额。
• description（选填）— 该条目的备注信息。
• tx_hash（选填）— 该条目的交易哈希。
• status（必填）— 条目执行状态，可能的值：Pending、Processing、Completed、Failed、NotExecuted。
• validation_status（必填）— 条目校验状态，可能的值：Pending、Validated、ValidationFailed、NotExecuted。
• failed_reason（选填）— 该条目失败的原因。
• created_timestamp（必填）— 创建时间，Unix 时间戳（秒）。
• updated_timestamp（必填）— 最后更新时间，Unix 时间戳（秒）。

​

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. 结算网络相关

​

payment.transaction.settlement_network.created

​

payment.transaction.settlement_network.completed

​

交易字段

• transaction_id（string，UUID，必填）— 交易 ID。
• cobo_id（string，选填）— 用于追踪交易的 Cobo ID。
• request_id（string，选填）— 用于追踪交易请求的请求 ID。
• type（string，选填）— 交易类型。
• status（string，必填）— 交易状态（例如 Submitted、PendingScreening、Confirming、Completed、Failed、Rejected）。完整生命周期请参考交易状态与子状态。PendingAuthorization 状态既包含人工审批环节，也包含内部自动化的风控/KYT/合规检查——处于该状态不一定需要人工操作。
• sub_status（string，选填）— 比 status 更细粒度的子状态（例如 PendingApproverCheck、RejectedKYT、FailedOnChain）。完整列表请参考同一篇交易状态与子状态。
• failed_reason（string，选填）— 交易失败原因。仅在审批失败和签名失败时返回。
• initiator（string，选填）— 交易发起者。
• chain_id（string，选填）— 链 ID。
• token_id（string，选填）— 代币 ID。
• transaction_hash（string，选填）— 链上交易哈希（txid）。仅在交易广播上链后才会返回，广播前可能为 null 或不存在——与之不同，transaction_id 在交易创建时即分配且始终存在。
• source（object，必填）— 充币来源，通常为外部钱包地址（source_type: DepositFromAddress）。
• destination（object，必填）— 充币目标，通常为充值地址（destination_type: DepositToAddress），主要子字段包括：
  • address — 到账地址。
  • amount — 到账金额。例如充入 1.5 USDT，则该值为 1.5。
  • memo — 用于识别交易归属账户的 memo（仅部分链）。
• result（object，选填）— 交易结果。
• fee（object，选填）— 交易手续费，其结构取决于链的手续费模型（例如 EIP-1559、UTXO）。
• confirmed_num（integer，选填）— 该交易已收到的确认数。
• confirming_threshold（integer，选填）— 判定交易安全所需的最低确认数（例如比特币交易通常为 6）。
• block_info（object，选填）— 交易所在区块的信息：
  • block_number — 区块高度。
  • block_timestamp — 区块创建时间，Unix 时间戳（毫秒）。
  • block_hash — 区块哈希。
• raw_tx_info（object，选填）— 原始交易信息：
  • used_nonce — 交易 nonce。
  • selected_utxos — 该交易消耗的 UTXO。
  • raw_tx — 原始交易数据。
  • unsigned_raw_tx — 未签名的原始交易数据。
  • utxo_changes — 交易中的 UTXO 找零输出。
• replacement（object，选填）— 当该交易替换了另一笔交易、或被另一笔交易替换（丢弃/重发/加速）时返回：
  • replaced_by_type / replaced_type — 替换类型：Drop、Resend 或 SpeedUp。
  • replaced_by_transaction_id / replaced_by_transaction_hash — 替换了该交易的交易 ID/哈希。
  • replaced_transaction_id / replaced_transaction_hash — 被该交易替换的交易 ID/哈希。
• created_timestamp（integer，int64，必填）— 创建时间，Unix 时间戳（毫秒）。
• updated_timestamp（integer，int64，必填）— 最后更新时间，Unix 时间戳（毫秒）。

​

Webhook 消息示例

{
  "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",
    "status": "Submitted",
    "chain_id": "ETH",
    "token_id": "ETH_USDT",
    "transaction_hash": "239861be9a4afe080c359b7fe4a1d035945ec46256b1a0f44d1267c71de8ec28",
    "source": { "source_type": "DepositFromAddress" },
    "destination": { "destination_type": "DepositToAddress" },
    "created_timestamp": 1701396866000,
    "updated_timestamp": 1701396866000,
    "acquiring_type": "TopUp",
    "payer_id": "P20250619T0310056d7aa",
    "custom_payer_id": "user_abc_10001"
  },
  "status": "Success"
}

​

提示

• 若需要根据 Webhook 通知及时更新余额，您可以：在接收到 Webhook 时，立即调用 List merchant balances 或 Get developer balances 接口获得准确的余额信息，再进行内部记账。
• 若需要及时知道 Webhook 所指交易引发的扣费信息，以便于关联交易和扣费进行对账，您可以：使用对应的查询交易信息接口和 Generate reports 获取扣费报表，来做数据的核对。
• 若需要及时知道 Webhook 所指交易引发的 Fee Station 余额的变动情况，保证后续不因 Fee Station 余额不足而影响业务，您可以：定期调用 List Fee Station token balance 查询 Fee Station 余额，并根据业务的消耗频率做内部报警策略，避免欠费影响正常业务运行。