Skip to main content
高级事件汇报的是底层链上交易的细节,只在您需要关心这些细节时才需要订阅,例如确认数、链上交易手续费明细、区块信息,或替换(丢弃、重发、加速)情况。 请先阅读事件概述了解外层结构、去重方式以及所有事件通用的规则。

本页的事件

payment.transaction.created

触发条件: 充值地址收到一笔新的充值。仅充值模式。同一个事实也会通过 payment.topup.updated 的 status 为 Detected 送达。 事件内容: 共用交易字段,外加以下字段。

payment.transaction.completed

触发条件: 一笔入金通过合规筛查并已入账。两种收款模式都有。对于分多笔付清的订单,每笔资金入账时各触发一次;订单事件汇报的是累计结果,参见少付、多付、部分付款和晚付。 事件内容: 共用交易字段,外加以下字段。哪几个字段有值取决于收款模式。

payment.transaction.failed

触发条件: 一笔入金失败或被拒绝,例如合规筛查未通过。两种收款模式都有。 事件内容: 共用交易字段,外加以下字段。
失败的具体原因请读该笔业务自己的事件里的 failed_reason;交易字段里的 failed_reason 是自由文本,且仅在审批失败和签名失败时有值。

payment.transaction.late

触发条件: 订单进入终态后,又收到一笔通过合规筛查的入金。仅订单模式。它不会重开订单,也不会改变订单的终态。同一个事实也会通过 payment.order.updated 的 notice_type 为 LatePaymentReceived 送达,参见少付、多付、部分付款和晚付。 事件内容: 共用交易字段,外加以下字段。

payment.order.status.updated

与 payment.order.updated 同时投递,返回的是该订单底层交易的细节,包括 transactions 数组和费用字段。 触发条件: 支付订单状态变更,仅订单模式。会触发的节点包括 Pending(通过支付链接成功创建订单)、Completed(有效期内收到全额付款)、Underpaid(有效期内有已完成的入金但不足额)、Expired(有效期内没有已完成的入金,或订单已被取消)。 事件内容:
完整字段说明请参考 Get pay-in order information。

payment.refund.status.updated

与 payment.refund.updated 同时投递,返回的是该退款底层交易的细节,包括 transactions 数组和费用字段。 触发条件: 退款单状态变更。关键节点为 Pending(通过退款链接成功创建退款单)、Completed(全部退款交易完成)、Failed(全部退款交易失败)。 事件内容:
完整说明请参见 Get refund order information。

payment.payout.status.updated

与 payment.payout.updated 同时投递,返回的是该次转出底层交易的细节,包括 transactions 数组和 payout_items。 触发条件: 资金转出或转账请求状态变更。Completed 表示全部转账完成,PartiallyCompleted 表示部分完成、部分失败,Failed 表示全部失败,RejectedByBank 表示收款银行拒绝了 Off-Ramp 转出。 事件内容:
完整说明请参见 Get payout information。

payment.bulk_send.status.updated

与 payment.bulk_send.updated 同时投递,返回的是该批次底层交易的细节。 触发条件: 批量下发请求状态变更。Completed 表示全部下发完成,PartiallyCompleted 表示部分完成、部分失败,Failed 表示全部失败。 事件内容:
完整说明请参见 Get bulk send information。

payment.bulk_send.item.status.updated

与 payment.bulk_send.item.updated 同时投递,返回的是该条目底层交易的细节,包括 validation_status 和 tx_hash。 触发条件: 单个批量下发条目进入终态(Completed、Failed、NotExecuted)。Pending 和 Processing 不发事件。 事件内容:
要测试投递到您已注册的 Webhook 接收端,请使用 Trigger test webhook event,并将 event_type 设为 payment.bulk_send.item.status.updated。

交易字段

以下字段出现在所有 payment.transaction.* 事件中。并非每个字段在每种场景下都有值。
  • transaction_id(string,UUID,必填)—— 交易 ID。
  • cobo_id(string,选填)—— 用于追踪交易的 Cobo ID。
  • request_id(string,选填)—— 用于追踪交易请求的请求 ID。
  • type(string,选填)—— 交易类型。
  • status(string,必填)—— 交易状态,例如 Submitted、PendingScreening、Confirming、Completed、Failed、Rejected。完整生命周期参见 Transaction statuses and sub-statuses。其中 PendingAuthorization 既涵盖人工审批环节,也涵盖内部自动的风控、KYT、合规检查,不一定需要人工操作。
  • sub_status(string,选填)—— 与 status 并列的更细粒度状态,例如 PendingApproverCheck、RejectedKYT、FailedOnChain。完整取值同样参见上述状态与子状态文档。
  • failed_reason(string,选填)—— 交易失败的原因,仅在审批失败和签名失败时有值。它是一个自由文本字符串,与各支付业务的事件携带的 { code, message } 对象不同。
  • initiator(string,选填)—— 交易发起人。
  • chain_id(string,选填)—— 链 ID。
  • token_id(string,选填)—— token 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 —— 用于识别应入账到哪个账户的备注,仅部分链有。
  • 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 时间戳(毫秒)。

示例

本示例仅供说明,由 Payment 规范中的字段定义构造而成;实际投递的 Webhook 中可选字段可能不存在。