Webhook Beta

本文档面向 API 接入方 / 集成伙伴。描述通过 webhook 推送的业务事件清单、消息格式、对接规范。

UAT环境IP：47.242.151.41
生产环境IP：请联系工作人员
⚠️请添加本IP至贵公司IP白名单，非本IP的webhook一律非可信

1. 概述

本平台通过 HTTP webhook 主动向您预先配置的端点推送业务事件。当用户在平台上的关键状态发生变化（开卡、KYC 审核、提现完成等）时，平台会立即向您的端点发送一条 JSON 消息。

适用场景

实时同步用户业务状态到您方系统

触发您方的下游业务流程（如返佣、通知、报表）

实时对账（资金流、卡操作）

不适用场景

不可作为账务一致性的唯一来源——webhook 是通知，不是事务。关键账务请配合定期对账 / API 查询。

不可用于强实时控制——存在网络延迟、重试间隔等不确定因素，毫秒级触发请使用同步 API。

2. 事件类型快速索引

按业务域归类的完整事件列表：

域	event_type	性质
kyc	`person_kyc_submitted`	异步
	`person_kyc_approved`	异步（含 PII）
	`person_kyc_rejected_retry`	异步
	`person_kyc_rejected_final`	异步
aml	`person_aml_success`	异步
	`person_aml_failed`	异步
crypto_withdrawal	`crypto_withdrawal_submitted`	同步
	`crypto_withdrawal_completed`	异步（链上确认）
	`crypto_withdrawal_failed`	异步 / 同步（视 failure_source）
	`crypto_withdrawal_cancel_success`	同步
	`crypto_withdrawal_cancel_failed`	同步
crypto_deposit	`crypto_deposit_completed`	异步（入金审核通过，余额已增加）
	`crypto_deposit_rejected`	异步（入金被管理员拒绝）
crypto_to_card_transfer	`crypto_to_card_transfer_success`	同步
	`crypto_to_card_transfer_failed`	同步
	`crypto_to_card_transfer_executed`	异步（渠道确认）
	`crypto_to_card_transfer_execute_failed`	异步（渠道拒绝）
inner_transfer	`inner_transfer_out_success`	同步（转出方）
	`inner_transfer_in_success`	同步（转入方）
	`inner_transfer_failed`	同步（转出方）

详细字段、触发时机、JSON 示例见 §5 事件目录。

3. 事件交付模型

HTTP 协议

项	值
Method	`POST`
Content-Type	`application/json`
Body	UTF-8 编码的 JSON（见第 4 节）
期望响应	HTTP `200`（任何 2xx 视为 ACK 成功）
响应 body	任意（建议返回 `{"ok": true}`）
超时	您方应在 5 秒内返回响应；超时视为投递失败

重试策略

如果您的端点未在超时窗口内返回 2xx，平台会按以下退避间隔重试：

1m → 5m → 20m → 1h → 6h → 24h

共最多 6 次重试（含首次共 7 次投递），跨度约 31 小时。重试后仍失败的消息将进入死信队列，不再自动重投——可联系运维人工补推。

投递保证

至少一次（at-least-once）：同一条 message_id 可能被推送多次（重试场景）。您方必须实现幂等去重（见第 6 节）。

乱序可能：网络重试 + 多并发投递可能导致事件乱序到达（如 success 比 submitted 先到）。请基于 occurred_at 时间戳和业务状态机判断顺序，不要假设到达顺序。

端点配置

接入时，请提供：

项	说明
Webhook URL	您方接收事件的 HTTPS 端点

请求头

平台推送 webhook 事件时，会在 HTTP 请求头中携带以下相关字段：

请求头字段	示例值	说明
`x-webhook-message-id`	`59d9ece5-cc1c-423a-81fa-41e943e1de30`	消息唯一 ID，与请求体中 `message_id` 一致
`x-webhook-event-type`	`delivery_address_created_success`	事件类型，与请求体中 `event_type` 一致
`x-webhook-attempt`	`1`	本次投递的尝试次数（首次为 1，重试依次递增）

4. 消息格式

Envelope

所有事件共享统一外层结构：

{
  "message_id": "9b7f3e22-c9d4-4f1a-8a45-1c4d3e7b2f88",
  "event_type": "card_created_success",
  "occurred_at": 1731000000000,
  "payload": {
    "account_id": "a8f1...",
    "card_id": "card_xx...",
    "...": "..."
  }
}

字段	类型	说明
`message_id`	string (UUID v4)	消息唯一 ID；用于幂等去重，必须保留并入库
`event_type`	string	事件类型，见第 2/5 节。
`occurred_at`	number (ms timestamp)	业务事件发生时间（毫秒 Unix 时间戳）；用于判断事件顺序
`payload`	object	事件特定数据，不同 `event_type` 结构不同——见第 5 节

命名约定

event_type 命名遵循 <domain>_<action>_<result> 模式：

_success 后缀：动作成功完成

_failed 后缀：动作失败（payload 含 error_code / error_message）

部分事件用状态名（如 _submitted / _completed / _approved / _rejected_retry）

5. 事件目录

按业务域分组。每个事件含触发时机 + 完整 payload 字段表 + JSON 示例。

字段表中 ? 表示可选（特定场景可能不存在）。

⚠️ 标注 PII 的字段含个人敏感信息；标注 金融敏感 的字段需符合金融合规要求。

5.3 KYC 域

5.3.1 `person_kyc_submitted` — KYC 资料已提交

触发时机：用户完成资料提交，进入审核中状态。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`ky_case_id`	string	✓	KYC case ID（用于查询 KYC 状态）
`kyc_id`	string	✓	KYC 记录 ID

示例：

{
  "message_id": "d3e4f5a6-7b8c-9d0e-1f20-3a4b5c6d7088",
  "event_type": "person_kyc_submitted",
  "occurred_at": 1731000900000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "ky_case_id": "case_xxxx",
    "kyc_id": "kyc_yyyy"
  }
}

5.3.2 `person_kyc_approved` — KYC 审核通过

触发时机：KYC 审核通过，用户身份信息已落库。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`ky_case_id`	string	✓	KYC case ID
`kyc_id`	string	✓	KYC 记录 ID
`legal_name`	string	✓	PII（法定姓名，中文 / 本地化）
`legal_name_en`	string	✓	PII（法定姓名，英文）
`country`	string	✓	国家 ISO 代码
`birthday`	string	✓	PII（生日，YYYY-MM-DD）
`id_type`	string	✓	证件类型
`id_number`	string	✓	PII（证件号）
`review_time`	string (ISO 8601)	✓	审核完成时间

⚠️ 此事件含完整 PII，请按数据保护法规处理（最小权限、加密存储、访问审计）。

示例：

{
  "message_id": "f5a6b7c8-9d0e-1f20-3a4b-5c6d7e8f9000",
  "event_type": "person_kyc_approved",
  "occurred_at": 1731001000000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "ky_case_id": "case_xxxx",
    "kyc_id": "kyc_yyyy",
    "legal_name": "John Smith",
    "legal_name_en": "John Smith",
    "country": "US",
    "birthday": "1990-01-15",
    "id_type": "passport",
    "id_number": "E12345678",
    "review_time": "2026-05-13T10:30:00.000Z"
  }
}

5.3.3 `person_kyc_rejected_retry` — KYC 暂时拒绝（可重提）

触发时机：KYC 审核拒绝，用户可补充资料后重新提交；尚未达到最大失败次数。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`ky_case_id`	string	✓	KYC case ID
`kyc_id`	string	✓	KYC 记录 ID
`fail_count`	number	✓	累计失败次数（本次拒绝后）
`max_fail_count`	number	✓	最大允许失败次数（达到后自动转为最终拒绝）
`review_answer`	string	✓	审核答复（如 `RED`）
`reject_labels`	string[]	✓	拒绝原因标签数组

示例：

{
  "message_id": "172839ab-cdef-0123-4567-89abcdef0123",
  "event_type": "person_kyc_rejected_retry",
  "occurred_at": 1731001100000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "ky_case_id": "case_xxxx",
    "kyc_id": "kyc_yyyy",
    "fail_count": 2,
    "max_fail_count": 5,
    "review_answer": "RED",
    "reject_labels": ["BAD_PHOTO_QUALITY", "ID_MISMATCH"]
  }
}

5.3.4 `person_kyc_rejected_final` — KYC 最终拒绝（不可重提）

触发时机：KYC 最终拒绝，或累计失败次数达到上限自动升级为最终拒绝。用户不可再发起 KYC。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`ky_case_id`	string	✓	KYC case ID
`kyc_id`	string	✓	KYC 记录 ID
`fail_count`	number	✓	累计失败次数（含本次）
`review_answer`	string	✓	审核答复
`reject_labels`	string[]	✓	拒绝原因标签数组

⚠️ 收到此事件后，建议下游锁定该用户禁止再发起 KYC 流程。

示例：

{
  "message_id": "839abcde-f012-3456-789a-bcdef0123455",
  "event_type": "person_kyc_rejected_final",
  "occurred_at": 1731001200000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "ky_case_id": "case_xxxx",
    "kyc_id": "kyc_yyyy",
    "fail_count": 5,
    "review_answer": "RED",
    "reject_labels": ["FORGERY", "BLOCKED_LIST_MATCH"]
  }
}

5.4 反洗钱域（aml）

5.4.1 `person_aml_success` — AML 检查通过

触发时机：用户 AML 检查通过 + 姓名校验通过，账户反洗钱状态进入 success。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`ky_case_id`	string	✓	KYC case ID
`kyc_id`	string	✓	KYC 记录 ID
`review_answer`	string	✓	审核答复（通过时为 `GREEN`）

示例：

{
  "message_id": "abcdef01-2345-6789-abcd-ef0123456788",
  "event_type": "person_aml_success",
  "occurred_at": 1731001300000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "ky_case_id": "case_xxxx",
    "kyc_id": "kyc_yyyy",
    "review_answer": "GREEN"
  }
}

5.4.2 `person_aml_failed` — AML 检查失败

触发时机：AML 或姓名校验任一失败，账户反洗钱状态进入 failed。需人工介入处理。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`ky_case_id`	string	✓	KYC case ID
`kyc_id`	string	✓	KYC 记录 ID
`review_answer`	string	✓	审核答复（`RED` 或其他）
`aml_check_success`	boolean	✓	AML 检查本身是否通过
`name_check_success`	boolean	✓	姓名校验是否通过
`reject_labels`	string[]	✓	拒绝原因标签数组

示例：

{
  "message_id": "cdef0123-4567-89ab-cdef-012345678900",
  "event_type": "person_aml_failed",
  "occurred_at": 1731001400000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "ky_case_id": "case_xxxx",
    "kyc_id": "kyc_yyyy",
    "review_answer": "RED",
    "aml_check_success": false,
    "name_check_success": true,
    "reject_labels": ["PEP_MATCH", "SANCTIONS_LIST_HIT"]
  }
}

5.5 加密货币提现 / 入金域（crypto_withdrawal + crypto_deposit）

提现是多阶段事件：submitted → 审核 → 链上 → completed / failed。可能延迟几十分钟到几小时。

5.5.1 `crypto_withdrawal_submitted` — 提现请求受理

触发时机：用户调用提现接口、参数校验通过、资金已冻结、订单已落库。链上未发起。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`transaction_id`	string	✓	提现交易唯一 ID
`transaction_id_no`	string?		业务订单号
`currency`	string	✓	提现币种
`amount`	number	✓	提现金额（不含手续费）
`fee`	number	✓	手续费
`address`	string	✓	目标链上地址
`wallet_id`	string	✓	钱包 ID
`chain`	string	✓	链名（如 `Ethereum`、`Tron`）

示例：

{
  "message_id": "ef012345-6789-abcd-ef01-234567890011",
  "event_type": "crypto_withdrawal_submitted",
  "occurred_at": 1731001500000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "transaction_id": "tx_zzzz",
    "transaction_id_no": "WD20260513001",
    "currency": "USDT",
    "amount": 100,
    "fee": 1,
    "address": "TXyZ1234567890abcdefghij",
    "wallet_id": "wallet_xxxx",
    "chain": "Tron"
  }
}

5.5.2 `crypto_withdrawal_completed` — 提现链上完成

触发时机：链上确认成功。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`transaction_id`	string	✓	提现交易唯一 ID
`transaction_id_no`	string?		业务订单号
`currency`	string	✓	提现币种
`amount`	number	✓	提现金额
`address`	string	✓	目标链上地址
`chain_tx_id`	string	✓	链上交易 hash

示例：

{
  "message_id": "01234567-89ab-cdef-0123-456789abcdee",
  "event_type": "crypto_withdrawal_completed",
  "occurred_at": 1731001600000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "transaction_id": "tx_zzzz",
    "transaction_id_no": "WD20260513001",
    "currency": "USDT",
    "amount": 100,
    "address": "TXyZ1234567890abcdefghij",
    "chain_tx_id": "0xabc1234567890def..."
  }
}

5.5.3 `crypto_withdrawal_failed` — 提现失败

触发时机：以下任一情况：

链上失败（failure_source = "chain"）

平台人工审核拒绝（failure_source = "admin_rejected"）

平台人工审核终止（failure_source = "admin_terminated"）

⚠️ 失败已自动退款，用户余额已恢复。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`transaction_id`	string	✓	提现交易唯一 ID
`transaction_id_no`	string?		业务订单号
`currency`	string	✓	提现币种
`amount`	number	✓	提现金额
`address`	string?		目标链上地址
`failure_source`	`'chain' \| 'admin_rejected' \| 'admin_terminated'`	✓	失败原因分类
`chain_status`	string?		仅 `failure_source=chain` 时存在；链上状态描述
`chain_tx_id`	string?		链上 hash（部分场景失败时可能存在）
`review_remark`	string?		仅 `failure_source=chain` 时存在；渠道审核备注
`review_comment`	string?		仅 admin 失败时存在；审核备注

示例（链上失败）：

{
  "message_id": "23456789-abcd-ef01-2345-6789abcdeffe",
  "event_type": "crypto_withdrawal_failed",
  "occurred_at": 1731001700000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "transaction_id": "tx_zzzz",
    "transaction_id_no": "WD20260513001",
    "currency": "USDT",
    "amount": 100,
    "address": "TXyZ1234567890abcdefghij",
    "failure_source": "chain",
    "chain_status": "REJECTED",
    "review_remark": "Risk control: target address blacklisted"
  }
}

示例（人工拒绝）：

{
  "message_id": "456789ab-cdef-0123-4567-89abcdef0122",
  "event_type": "crypto_withdrawal_failed",
  "occurred_at": 1731001710000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "transaction_id": "tx_zzzz",
    "transaction_id_no": "WD20260513002",
    "currency": "USDT",
    "amount": 100,
    "address": "TXyZ1234567890abcdefghij",
    "failure_source": "admin_rejected",
    "review_comment": "Suspicious activity, requires user verification"
  }
}

5.5.4 `crypto_withdrawal_cancel_success` — 提现取消成功

触发时机：用户主动取消未审核的提现订单，退款已完成。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`transaction_id`	string	✓	已取消的提现交易 ID
`transaction_id_no`	string?		业务订单号
`currency`	string	✓	提现币种
`amount`	number	✓	提现金额（已退回用户余额）
`address`	string?		原目标链上地址

示例：

{
  "message_id": "6789abcd-ef01-2345-6789-abcdef012344",
  "event_type": "crypto_withdrawal_cancel_success",
  "occurred_at": 1731001800000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "transaction_id": "tx_aaaa",
    "transaction_id_no": "WD20260513003",
    "currency": "USDT",
    "amount": 50,
    "address": "TXyZabcdef1234567890ijkl"
  }
}

5.5.5 `crypto_withdrawal_cancel_failed` — 提现取消失败

触发时机：取消流程抛异常（订单不存在、订单已审核失败、状态不允许取消等）。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`transaction_id`	string	✓	尝试取消的提现交易 ID
`error_code`	number	✓	错误码
`error_message`	string	✓	错误描述

示例：

{
  "message_id": "89abcdef-0123-4567-89ab-cdef01234566",
  "event_type": "crypto_withdrawal_cancel_failed",
  "occurred_at": 1731001810000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "transaction_id": "tx_aaaa",
    "error_code": 210001,
    "error_message": "Transaction status does not allow cancellation"
  }
}

5.5.6 `crypto_deposit_completed` — 加密货币入金完成

触发时机：用户加密钱包收到链上入金、平台审核通过、账户余额已增加。3 路覆盖——Cactus webhook 自动审核、Fireblocks webhook 自动审核、管理员手动审核——3 个触发路径最终统一在 reviewTransaction 处 emit。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`transaction_id`	string	✓	入金交易唯一 ID
`transaction_id_no`	string?		业务订单号
`currency`	string	✓	入金币种
`amount`	number	✓	入金金额
`address`	string?		入金地址（用户的链上地址）
`chain_tx_id`	string?		链上交易 hash
`wallet_id`	string?		入金到的钱包 ID

示例：

{
  "message_id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7088",
  "event_type": "crypto_deposit_completed",
  "occurred_at": 1731003400000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "transaction_id": "tx_deposit_xxxx",
    "transaction_id_no": "DEPOSIT_20260514001",
    "currency": "USDT",
    "amount": 1000,
    "address": "TXyZabcdef1234567890ijkl",
    "chain_tx_id": "0xabc1234567890def...",
    "wallet_id": "wallet_xxxx"
  }
}

5.5.7 `crypto_deposit_rejected` — 加密货币入金被拒绝

触发时机：管理员手动拒绝入金（罕见场景，如合规审查不通过、欺诈嫌疑）。

⚠️ 收到此事件意味着入金未到账。需通知用户并跟进。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`transaction_id`	string	✓	入金交易唯一 ID
`transaction_id_no`	string?		业务订单号
`currency`	string	✓	入金币种
`amount`	number	✓	原入金金额
`review_comment`	string?		拒绝原因（管理员填写）
`admin_id`	string	✓	操作管理员 ID

示例：

{
  "message_id": "5c6d7e8f-9a0b-1c2d-3e4f-5a6b7c8d9099",
  "event_type": "crypto_deposit_rejected",
  "occurred_at": 1731003500000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "transaction_id": "tx_deposit_xxxx",
    "transaction_id_no": "DEPOSIT_20260514002",
    "currency": "USDT",
    "amount": 1000,
    "review_comment": "Source address on sanctions list, deposit blocked",
    "admin_id": "admin_yyyy"
  }
}

5.6 钱包到卡充值域（crypto_to_card_transfer）

5.6.1 `crypto_to_card_transfer_success` — 钱包到卡充值成功（同步）

触发时机：用户将加密钱包余额充值到卡片、recharge 事务（含限额校验 / 奖励金扣除 / 手续费计算 / 卡余额增加）全部完成。这是请求受理事件；Wasabi 真正确认到卡后会收到异步事件 crypto_to_card_transfer_executed（见 5.6.3）。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`card_id`	string	✓	目标卡片 ID
`channel_card_id`	string	✓	渠道侧卡号 / 金融敏感
`wallet_id`	string	✓	源钱包 ID
`wallet_currency`	string	✓	钱包币种
`input_amount`	number	✓	用户输入金额（按钱包币种）
`amount_usd`	number	✓	折算为 USD 的金额
`use_reward`	boolean	✓	是否使用奖励金
`card_transaction_id`	string		内部卡交易 ID
`crypto_transaction_id`	string		内部加密交易 ID
`fee`	number		手续费（USD）
`settle_amount`	number		实际到卡金额（USD，含奖励金）
`total_amount_usd`	number		总金额（USD，用户输入 + 奖励金）
`reward_amount_usd`	number		使用的奖励金金额（USD）

示例：

{
  "message_id": "abcdef01-2345-6789-abcd-ef0123456788",
  "event_type": "crypto_to_card_transfer_success",
  "occurred_at": 1731001900000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "card_id": "card_zzzz",
    "channel_card_id": "5188xxxxxxxx1234",
    "wallet_id": "wallet_xxxx",
    "wallet_currency": "USDT",
    "input_amount": 100,
    "amount_usd": 100,
    "use_reward": true,
    "card_transaction_id": "card_tx_xxxx",
    "crypto_transaction_id": "crypto_tx_yyyy",
    "fee": 1,
    "settle_amount": 105,
    "total_amount_usd": 105,
    "reward_amount_usd": 5
  }
}

5.6.2 `crypto_to_card_transfer_failed` — 钱包到卡充值失败（同步）

触发时机：sync 阶段抛异常（余额不足、卡状态异常、汇率转换失败、渠道同步拒绝等）。卡余额未变更。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`card_id`	string	✓	目标卡片 ID
`channel_card_id`	string	✓	渠道侧卡号 / 金融敏感
`wallet_id`	string	✓	源钱包 ID
`wallet_currency`	string	✓	钱包币种
`input_amount`	number	✓	用户输入金额（按钱包币种）
`amount_usd`	number \| null	✓	折算为 USD 的金额；汇率转换前就失败时为 null
`use_reward`	boolean	✓	是否使用奖励金
`error_code`	number	✓	错误码
`error_message`	string	✓	错误描述

示例：

{
  "message_id": "cdef0123-4567-89ab-cdef-01234567890a",
  "event_type": "crypto_to_card_transfer_failed",
  "occurred_at": 1731001910000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "card_id": "card_zzzz",
    "channel_card_id": "5188xxxxxxxx1234",
    "wallet_id": "wallet_xxxx",
    "wallet_currency": "USDT",
    "input_amount": 100,
    "amount_usd": 100,
    "use_reward": false,
    "error_code": 200001,
    "error_message": "Insufficient balance"
  }
}

5.6.3 `crypto_to_card_transfer_executed` — 钱包到卡充值渠道确认（异步终态）

触发时机：渠道侧异步确认充值已到卡。与同步事件 crypto_to_card_transfer_success 配对存在——同步事件表示"接口调用接受请求"，本事件表示"渠道侧资金真正到账"。可订阅其中一个或两个。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`card_id`	string	✓	目标卡片 ID
`channel_card_id`	string	✓	渠道侧卡号 / 金融敏感
`first8`	string	✓	卡号前 8 位 / 金融敏感
`last4`	string	✓	卡号后 4 位 / 金融敏感
`order_no`	string	✓	订单号
`amount`	number	✓	充值金额
`currency`	string	✓	交易币种
`received_amount`	number		卡侧实际到账金额
`received_currency`	string		卡侧到账币种
`transaction_time`	number	✓	交易时间（毫秒 Unix 时间戳）

示例：

{
  "message_id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9077",
  "event_type": "crypto_to_card_transfer_executed",
  "occurred_at": 1731003200000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "card_id": "card_zzzz",
    "channel_card_id": "5188xxxxxxxx1234",
    "first8": "51880001",
    "last4": "1234",
    "order_no": "RECHARGE_20260513001",
    "amount": 100,
    "currency": "USD",
    "received_amount": 100,
    "received_currency": "USD",
    "transaction_time": 1731003200000
  }
}

5.6.4 `crypto_to_card_transfer_execute_failed` — 钱包到卡充值渠道异步拒绝

触发时机：渠道侧异步拒绝充值（已自动退款回钱包）。注意：此前可能已收到同步 crypto_to_card_transfer_success 事件，现在需冲销该事件——资金已退回钱包。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`card_id`	string	✓	目标卡片 ID
`channel_card_id`	string	✓	渠道侧卡号 / 金融敏感
`first8`	string	✓	卡号前 8 位 / 金融敏感
`last4`	string	✓	卡号后 4 位 / 金融敏感
`order_no`	string	✓	订单号
`amount`	number	✓	原计划充值金额
`currency`	string	✓	交易币种
`error_status`	string	✓	渠道侧错误状态
`error_message`	string	✓	错误描述

示例：

{
  "message_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1088",
  "event_type": "crypto_to_card_transfer_execute_failed",
  "occurred_at": 1731003210000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "card_id": "card_zzzz",
    "channel_card_id": "5188xxxxxxxx1234",
    "first8": "51880001",
    "last4": "1234",
    "order_no": "RECHARGE_20260513002",
    "amount": 100,
    "currency": "USD",
    "error_status": "fail",
    "error_message": "Card declined"
  }
}

5.7 站内用户转账域（inner_transfer）

站内用户互转：双端事件——成功时给转出方和转入方各发一条消息，account_id 分别对应该端账户。

5.7.1 `inner_transfer_out_success` — 站内转账转出成功（转出方视角）

触发时机：站内转账完成，转出方账户已扣款。account_id 为转出方账户。

字段	类型	必填	说明
`account_id`	string	✓	转出方账户 ID
`to_account_id`	string	✓	转入方账户 ID
`transaction_id`	string	✓	转出交易 ID
`paired_transaction_id`	string	✓	配对的转入交易 ID（同笔业务）
`currency`	string	✓	转出币种
`amount`	number	✓	转出金额（含手续费）
`fee`	number	✓	手续费
`transfer_type`	`'crypto' \| 'fiat'`	✓	转账类型
`from_uid`	string?		转出方业务编号
`to_uid`	string?		转入方业务编号

示例：

{
  "message_id": "ef012345-6789-abcd-ef01-23456789abcc",
  "event_type": "inner_transfer_out_success",
  "occurred_at": 1731002000000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "to_account_id": "b9e2c3f1-5678-9abc-def0-123456789012",
    "transaction_id": "tx_out_xxxx",
    "paired_transaction_id": "tx_in_yyyy",
    "currency": "USDT",
    "amount": 100,
    "fee": 1,
    "transfer_type": "crypto",
    "from_uid": "UID10001",
    "to_uid": "UID10002"
  }
}

5.7.2 `inner_transfer_in_success` — 站内转账转入成功（转入方视角）

触发时机：同 4.7.1 同一笔转账，但发给转入方。account_id 为转入方账户。

字段	类型	必填	说明
`account_id`	string	✓	转入方账户 ID
`from_account_id`	string	✓	转出方账户 ID
`transaction_id`	string	✓	转入交易 ID
`paired_transaction_id`	string	✓	配对的转出交易 ID
`currency`	string	✓	转入币种
`amount`	number	✓	实际到账金额（已扣手续费）
`transfer_type`	`'crypto' \| 'fiat'`	✓	转账类型
`from_uid`	string?		转出方业务编号
`to_uid`	string?		转入方业务编号

关联：out_success 和 in_success 通过 paired_transaction_id 关联——若同时订阅两端事件，可据此识别是同一笔业务。

示例：

{
  "message_id": "01234567-89ab-cdef-0123-456789abcdee",
  "event_type": "inner_transfer_in_success",
  "occurred_at": 1731002000000,
  "payload": {
    "account_id": "b9e2c3f1-5678-9abc-def0-123456789012",
    "from_account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "transaction_id": "tx_in_yyyy",
    "paired_transaction_id": "tx_out_xxxx",
    "currency": "USDT",
    "amount": 99,
    "transfer_type": "crypto",
    "from_uid": "UID10001",
    "to_uid": "UID10002"
  }
}

5.7.3 `inner_transfer_failed` — 站内转账失败

触发时机：站内转账事务整体失败（资金未扣、未到账）。仅给转出方发一条（转入方根本不知情），account_id 为转出方。

字段	类型	必填	说明
`account_id`	string	✓	转出方账户 ID
`to_account_id`	string	✓	转入方账户 ID
`currency`	string	✓	转出币种
`to_currency`	string	✓	转入币种
`amount`	number	✓	尝试转出的金额
`fee_amount`	number	✓	手续费
`transfer_type`	`'crypto' \| 'fiat'`	✓	转账类型
`error_code`	number	✓	错误码
`error_message`	string	✓	错误描述

示例：

{
  "message_id": "23456789-abcd-ef01-2345-6789abcdeffe",
  "event_type": "inner_transfer_failed",
  "occurred_at": 1731002100000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "to_account_id": "b9e2c3f1-5678-9abc-def0-123456789012",
    "currency": "USDT",
    "to_currency": "USDT",
    "amount": 100,
    "fee_amount": 1,
    "transfer_type": "crypto",
    "error_code": 200001,
    "error_message": "Insufficient balance"
  }
}

5.8 持卡人审核域（card_holder）

发生在用户 KYC 通过之后，由卡渠道侧执行的二次审核。决定该用户是否可以在此渠道开卡。

5.8.1 `card_holder_passed` — 持卡人审核通过

触发时机：渠道侧持卡人审核通过，用户可以进入开卡流程。

字段	类型	必填	说明
`account_id`	string	✓	账户 ID
`card_holder_task_id`	string	✓	持卡人审核任务 ID
`merchant_order_no`	string	✓	商户订单号
`holder_id`	string	✓	渠道侧持卡人 ID
`card_type_id`	string	✓	卡产品类型 ID
`support_physical`	boolean	✓	该卡产品是否支持实体卡

示例：

{
  "message_id": "9c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3099",
  "event_type": "card_holder_passed",
  "occurred_at": 1731003300000,
  "payload": {
    "account_id": "a8f1d2e0-1234-5678-9abc-def012345678",
    "card_holder_task_id": "task_xxxx",
    "merchant_order_no": "HOLDER_20260513001",
    "holder_id": "holder_yyyy",
    "card_type_id": "card_type_001",
    "support_physical": true
  }
}

6. 集成最佳实践

6.1 幂等处理（必须）

平台保证至少一次投递，重试会导致重复消息。您方必须基于 message_id 去重：

6.2 快速 ACK + 异步处理

webhook 端点应在 5 秒内返回 200。如果业务处理较慢：

6.3 处理乱序

不要假设事件按发生时间顺序到达。处理时检查业务状态机：

6.4 错误隔离

单个消息处理失败不应返回非 2xx 给平台（否则触发重试，可能放大问题）。建议：

业务异常 → 入死信表 / 告警，HTTP 仍返回 200

网络 / 平台原因（DB 挂等）→ 返回非 2xx 触发重试

6.5 健康监控

监控以下指标：

指标	告警阈值（建议）
webhook 接收量	突然降为 0 → 平台故障或网络问题
业务处理失败率	> 5% → 业务异常
死信积压量	> 100 → 人工排查

1. 概述#

适用场景#

不适用场景#

2. 事件类型快速索引#

3. 事件交付模型#

HTTP 协议#

重试策略#

投递保证#

端点配置#

请求头#

4. 消息格式#

Envelope#

命名约定#

5. 事件目录#

5.3 KYC 域#

5.3.1 person_kyc_submitted — KYC 资料已提交#

5.3.2 person_kyc_approved — KYC 审核通过#

5.3.3 person_kyc_rejected_retry — KYC 暂时拒绝（可重提）#

5.3.4 person_kyc_rejected_final — KYC 最终拒绝（不可重提）#

5.4 反洗钱域（aml）#

5.4.1 person_aml_success — AML 检查通过#

5.4.2 person_aml_failed — AML 检查失败#

5.5 加密货币提现 / 入金域（crypto_withdrawal + crypto_deposit）#

5.5.1 crypto_withdrawal_submitted — 提现请求受理#

5.5.2 crypto_withdrawal_completed — 提现链上完成#

5.5.3 crypto_withdrawal_failed — 提现失败#

5.5.4 crypto_withdrawal_cancel_success — 提现取消成功#

5.5.5 crypto_withdrawal_cancel_failed — 提现取消失败#

5.5.6 crypto_deposit_completed — 加密货币入金完成#

5.5.7 crypto_deposit_rejected — 加密货币入金被拒绝#

5.6 钱包到卡充值域（crypto_to_card_transfer）#

5.6.1 crypto_to_card_transfer_success — 钱包到卡充值成功（同步）#

5.6.2 crypto_to_card_transfer_failed — 钱包到卡充值失败（同步）#

5.6.3 crypto_to_card_transfer_executed — 钱包到卡充值渠道确认（异步终态）#

5.6.4 crypto_to_card_transfer_execute_failed — 钱包到卡充值渠道异步拒绝#

5.7 站内用户转账域（inner_transfer）#

5.7.1 inner_transfer_out_success — 站内转账转出成功（转出方视角）#

5.7.2 inner_transfer_in_success — 站内转账转入成功（转入方视角）#

5.7.3 inner_transfer_failed — 站内转账失败#

5.8 持卡人审核域（card_holder）#

5.8.1 card_holder_passed — 持卡人审核通过#

6. 集成最佳实践#

6.1 幂等处理（必须）#

6.2 快速 ACK + 异步处理#

6.3 处理乱序#

6.4 错误隔离#

6.5 健康监控#