事件与数据结构 - DCS Technical Documentation

📄 正文

组织开户、员工创建、建卡、卡状态、3DS 挑战、交易三态与入金预警，共 18 个出站事件，分五组。所有事件共用同一套信封——读 webhookType 再解析对应的 data 即可，接收端只需一个接口。

前置条件：先登记回调地址、准备好用 SK 复算 X-Signature。配置步骤与验签代码见 Webhook 配置。

信封

{
  "webhookId": "7800000000000000900",
  "webhookType": "ORGANIZATION_CREATED",
  "businessId": "7810000000000000123",
  "data": { },
  "notificationTime": "2026-08-25T02:30:00Z"
}

字段	类型	说明
`webhookId`	String	Webhook 唯一 ID。幂等键——同一事件的所有重试复用同一个
`webhookType`	String	事件类型码，大写下划线；全集见下表
`businessId`	String	本次内容的业务 ID。具体是哪种 ID 由 `webhookType` 决定，逐事件对应见下表
`data`	Object	业务数据，字段随 `webhookType` 不同
`notificationTime`	String	投递时刻，ISO-8601 UTC 零时区。取本次投递时刻，故同一事件的各次重试取值不同

信封与平台其他产品线的 Webhook 公共结构一致，您可以用同一套代码消费各产品线的事件。所有 ID 字段均为字符串；金额为字符串且不保证尾随零。

事件总览（18 个）

归类	`webhookType`	`businessId` 是	触发时机
组织	`ORGANIZATION_CREATED`	`organizationApplyId`	KYB 通过、组织创建成功
	`ORGANIZATION_REJECTED`	`organizationApplyId`	KYB 拒绝
	`ORGANIZATION_STATUS_CHANGED`	`organizationId`	组织限制项变更（新增 / 解除）
员工	`CUSTOMER_CREATED`	`customerApplyId`	KYC 通过、员工创建成功
	`CUSTOMER_REJECTED`	`customerApplyId`	KYC 拒绝
	`CUSTOMER_STATUS_CHANGED`	`customerId`	员工限制项变更（新增 / 解除）
卡	`CARD_CREATED`	`cardApplyId`	风控通过 + 建卡成功
	`CARD_REJECTED`	`cardApplyId`	风控拒绝或建卡异常
	`CARD_SHIPPED`	`cardId`	实体卡已制成并寄出（物流单号生成时，恰好一次）
	`CARD_ACTIVATED`	`cardId`	实体卡激活成功
	`CARD_STATUS_CHANGED`	`cardId`	卡状态变更（冻结 / 解冻 / 锁定 / 解锁 / 挂失 / 销卡）；虚实卡通用
	`AUTHORISATION_3DS_CHALLENGE`	`challengeId`	持卡人交易触发 3DS 挑战、需您参与验证或发码
交易	`CARD_TRANSACTION`	`transactionId`	卡授权 / release（通过与拒绝合一，由 `data.status` 区分）
	`CARD_TRANSACTION_SETTLEMENT`	`transactionId`	卡清算
	`CARD_TRANSACTION_DEBT`	`transactionId`	卡片进入欠款态
资金	`BANK_TRANSFER_INFO`	`depositId`	VA 入金到账（成功与失败均发，由 `data.status` 区分）
	`BALANCE_CHANGE`	`transactionId`	余额变动
	`LOW_BALANCE`	`organizationId`	资金池余额不足预警

除 ORGANIZATION_REJECTED（主体尚未创建）与三个交易事件（归属可由 cardId 稳定推导）外，所有事件的 data 都带 organizationId，您无需回查主体归属。

组织事件

`ORGANIZATION_CREATED`

字段	类型	说明
`organizationId`	String	组织 ID
`organizationType`	String	组织类型；当前值域仅 `COMPANY`
`organizationRef`	String	您侧的组织唯一编号（回显）
`organizationApplyId`	String	组织创建申请 ID
`status`	String	组织实体状态，固定 `ACTIVE`

`ORGANIZATION_REJECTED`

字段	类型	说明
`organizationType`	String	组织类型
`organizationRef`	String	您侧的组织唯一编号
`organizationApplyId`	String	组织创建申请 ID
`status`	String	申请状态，固定 `REJECTED`
`rejectMessage`	String	KYB 拒绝原因

本事件不含 organizationId——组织实体在 KYB 通过后才落库，被拒时尚不存在。请用 organizationRef 或 organizationApplyId 对号。另外这里的 status 指的是申请状态，与 ORGANIZATION_CREATED 里那个实体状态不是同一个对象。

`ORGANIZATION_STATUS_CHANGED`

镜像更新组织限制项，限制项变更落定后推送。

字段	类型	说明
`organizationId`	String	组织 ID
`organizationType`	String	组织类型
`addRestrictions`	Array<String>	本次新增的限制项
`removeRestrictions`	Array<String>	本次解除的限制项
`remark`	String	操作备注

员工事件

`CUSTOMER_CREATED`

字段	类型	说明
`customerId`	String	员工 ID
`customerRef`	String	您侧的员工唯一编号（回显）
`organizationId`	String	所属组织
`customerApplyId`	String	员工创建申请 ID
`status`	String	员工实体状态，固定 `ACTIVE`

`CUSTOMER_REJECTED`

字段	类型	说明
`customerRef`	String	您侧的员工唯一编号
`organizationId`	String	所属组织
`customerApplyId`	String	员工创建申请 ID
`status`	String	申请状态，固定 `REJECTED`
`rejectMessage`	String	KYC 拒绝原因

`CUSTOMER_STATUS_CHANGED`

镜像更新员工限制项。

字段	类型	说明
`customerId`	String	员工 ID
`organizationId`	String	所属组织
`addRestrictions`	Array<String>	本次新增的限制项
`removeRestrictions`	Array<String>	本次解除的限制项
`remark`	String	操作备注

卡事件

`CARD_CREATED`

字段	类型	说明
`cardId`	String	卡 ID
`organizationId`	String	卡所属组织
`cardApplyId`	String	卡申请 ID
`cardApplyRef`	String	您侧的申请唯一标识（回显）
`status`	String	卡状态，固定 `ACTIVE`

`CARD_REJECTED`

字段	类型	说明
`organizationId`	String	卡所属组织
`cardApplyId`	String	卡申请 ID
`cardApplyRef`	String	您侧的申请唯一标识（回显）
`status`	String	申请状态，固定 `REJECTED`
`rejectMessage`	String	失败原因（风控拒绝或建卡异常）

`CARD_SHIPPED`

物流单号生成时推送，恰好一次。

字段	类型	说明
`cardId`	String	卡 ID
`organizationId`	String	卡所属组织
`trackingNumber`	String	物流单号
`trackingCompanyName`	String	物流公司
`trackingNumberDate`	String	运单日期，`yyyy-MM-dd`

`CARD_ACTIVATED`

字段	类型	说明
`cardId`	String	卡 ID
`organizationId`	String	卡所属组织

`CARD_STATUS_CHANGED`

字段	类型	说明
`cardId`	String	卡 ID
`organizationId`	String	卡所属组织
`fromStatus`	String	变更前卡状态（7 态）
`toStatus`	String	变更后卡状态（7 态）

本事件不含「激活」与「过期」：激活单独发 CARD_ACTIVATED，过期当前无触发源。7 个卡状态见管理卡片。

`AUTHORISATION_3DS_CHALLENGE`

业务流程与回传见 3DS 挑战。

字段	类型	说明
`challengeId`	String	挑战 ID，回传时原样带回。您须按它去重
`status`	String	固定 `INIT`——挑战终态不经本事件通知
`cardId`	String	触发挑战的卡 ID
`organizationId`	String	卡所属组织
`expiryTime`	String	挑战过期时刻，ISO-8601 UTC（默认约 300 秒）
`currency`	String	交易币种，ISO-4217；与 `amount` 成对
`amount`	String	交易金额
`merchantId`	String	商户标识
`merchantName`	String	商户名称
`merchantCountryCode`	String	商户所属国，ISO-3166-1 alpha-2 两位大写
`mcc`	String	商户类别码，四位数字
`challengeFlowType`	String	`OOB` / `OTP_DELEGATE`——据此判断是否解析下面的密文字段
`challengeMethodType`	String	`DELEGATE_SCA_V1` / `SMS_OTP` / `EMAIL_OTP`

以下四个字段仅 challengeFlowType=OTP_DELEGATE 且入驻方配置 otpSendMode=ENTERPRISE 时填充：

字段	类型	说明
`encryptedOtpPasscode`	String	OTP 验证码密文
`encryptedPhoneNumber`	String	持卡人手机号密文
`encryptedEmail`	String	持卡人邮箱密文
`iv`	String	AES-GCM 初始向量（Base64），上述三个密文字段共用

解密：AES/GCM/NoPadding，128 位认证标签；密钥即接入方 SK（与请求签名同一把），与获取卡敏感信息同一套约定。

merchantCountryCode 的取值形态由 alpha-3（三位）改为 alpha-2（两位大写）——这是取值转换，不只是改名，解析逻辑需同步调整。

交易事件

三个交易事件描述的事实与账单明细同源，复用账单域的词条：panLast4 / transactionTime / transactionCategory / originalAmount+originalCurrency（交易原始金额）/ postAmount+postCurrency（入账金额）/ merchantName / mcc / merchantCountryCode。

交易事件不带 organizationId：归属可由 cardId 稳定推导——卡与所属组织的关系在建卡时确定且此后不变，您在 CARD_CREATED 里已经收到该卡的 organizationId。交易类事件量级远高于生命周期事件，故只带必需字段。需要按组织汇总时请用账单与交易查询。

`CARD_TRANSACTION`

授权与 release 合一，通过与拒绝由 status 区分。

字段	类型	说明
`transactionId`	String	交易唯一 ID，与账单流水同值，可直接对账
`originalTransactionId`	String	原交易 ID。仅 release / 冲正 / 退货类携带，其余场景不出参
`cardId`	String	卡 ID
`panLast4`	String	卡号后四位
`status`	String	授权结果：`APPROVED` / `DECLINED`
`direction`	String	借贷方向：`DEBIT` / `CREDIT` / `DEDUCT`。上游未下发借贷标识时整字段不出参
`originalAmount` / `originalCurrency`	String	交易原始金额与币种
`postAmount` / `postCurrency`	String	入账（记账口径）金额与币种
`transactionTime`	String	交易时刻，收单地当地时刻 `yyyy-MM-dd HH:mm:ss`
`transactionCategory`	String	`SALES` 消费 / `CASH_ADVANCE` 取现 / `PAYMENT` 还款 / `INSTALLMENT` 分期 / `INQUIRY` 查询 / `TRANSFER_OUT` 转出
`merchantName`	String	商户名称。上游原样透传，可能含地址
`merchantCountryCode`	String	商户所属国，alpha-2 两位大写
`mcc`	String	商户类别码，四位数字

{
  "webhookId": "7800000000000001201",
  "webhookType": "CARD_TRANSACTION",
  "businessId": "5185740066240791001",
  "notificationTime": "2026-08-25T02:30:00Z",
  "data": {
    "transactionId": "5185740066240791001",
    "cardId": "5136759791164443137",
    "panLast4": "4821",
    "status": "APPROVED",
    "direction": "DEBIT",
    "originalAmount": "128.50",
    "originalCurrency": "HKD",
    "postAmount": "16.47",
    "postCurrency": "USD",
    "transactionTime": "2026-08-25 10:30:00",
    "transactionCategory": "SALES",
    "merchantName": "STARBUCKS TSIM SHA TSUI HK",
    "merchantCountryCode": "HK",
    "mcc": "5812"
  }
}

`CARD_TRANSACTION_SETTLEMENT`

字段	类型	说明
`transactionId`	String	交易唯一 ID，与授权事件、账单流水同值
`cardId`	String	卡 ID
`panLast4`	String	卡号后四位
`direction`	String	借贷方向：`DEBIT` / `CREDIT`。备忘（MEMO）交易不推送本事件
`originalAmount` / `originalCurrency`	String	交易原始金额与币种
`postAmount` / `postCurrency`	String	清算入账金额与币种
`transactionTime`	String	交易时刻，收单地当地时刻
`transactionCategory`	String	`RETAIL` 消费 / `CASH` 取现 / `RETAIL_FEES` 消费费用 / `CASH_FEES` 取现费用 / `PAYMENT` 还款 / `DISPUTE_REGISTER` 争议登记 / `DISPUTE_RELEASE` 争议释放 / `RETAIL_INTEREST` 消费利息 / `CASH_ADVANCE_INTEREST` 取现利息 / `CARD_ANNUAL_FEE` 年费 / `CARD_PHYSICAL_FEE` 实体卡费 / `CARD_REPLACEMENT_FEE` 换卡费
`merchantName`	String	商户名称
`merchantCountryCode`	String	商户所属国，alpha-2
`mcc`	String	商户类别码

transactionCategory 在三处的值域各不相同：授权事件是 SALES / CASH_ADVANCE 等六值，清算事件是 RETAIL / CASH 等十二值，账单明细是 PURCHASE / REFUND 等七值。请按事件类型分别解析，不要共用一套枚举。

`CARD_TRANSACTION_DEBT`

进入欠款态时推送。

字段	类型	说明
`transactionId`	String	交易唯一 ID
`cardId`	String	欠款所属卡
`debtAmount` / `debtCurrency`	String	欠款金额与币种（交易口径）
`postAmount` / `postCurrency`	String	入账金额与币种（结算口径）
`transactionTime`	String	交易时刻，收单地当地时刻
`merchantName`	String	商户名称

本载荷有两个语义不同的金额（欠款额、入账额），故各自带限定语、不用裸 amount。

资金事件

`LOW_BALANCE`

资金池余额低于阈值时预警。阈值设置见公司维护。

字段	类型	说明
`organizationId`	String	触发预警的组织
`currency`	String	资金池币种：`USD` / `HKD`
`availableAmount`	String	当前可用余额，与 `currency` 成对
`thresholdAmount`	String	触发预警的阈值

{
  "webhookId": "7800000000000001001",
  "webhookType": "LOW_BALANCE",
  "businessId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "notificationTime": "2026-08-25T02:30:00Z",
  "data": {
    "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
    "currency": "USD",
    "availableAmount": "850.25",
    "thresholdAmount": "1000"
  }
}

`BANK_TRANSFER_INFO`

VA 入金到账，成功与失败均发，由 status 区分。

字段	类型	说明
`depositId`	String	平台侧充值流水 ID，与充值流水查询同名对齐
`organizationId`	String	收款资金池所属组织
`amount` / `currency`	String	入金金额与币种：`USD` / `HKD`
`payeeAccountNumber`	String	收款虚拟账号
`referenceCode`	String	银行业务参考号
`payerName`	String	付款方名称
`payerAccountNumber`	String	付款方账号
`payerBankCode`	String	付款方银行编码
`status`	String	入账状态：`SUCCESS` / `FAILED`
`errorCode` / `errorMessage`	String	仅 `FAILED` 时返回，成对出现

`BALANCE_CHANGE`

本事件口径未定稿，字段随时可能调整。 现行实现是账本变动日志原样转发，含内部字段，不符合本文的字段约定。接入前请与平台确认；本页不定义其 data 结构。

尚待定的三件事：通知覆盖哪些余额维度（组织资金池余额 / 自由余额 / 独立余额卡的卡余额）；如何标识主体与余额类型；是否每笔账变都发。

下一步

回调地址登记、验签与重试约定：Webhook 配置
3DS 挑战的接收与结果回传：3DS 挑战
用查询接口做兜底对账：账单与交易查询

​📄 正文

​信封

​事件总览（18 个）

​组织事件

​ORGANIZATION_CREATED

​ORGANIZATION_REJECTED

​ORGANIZATION_STATUS_CHANGED

​员工事件

​CUSTOMER_CREATED

​CUSTOMER_REJECTED

​CUSTOMER_STATUS_CHANGED

​卡事件

​CARD_CREATED

​CARD_REJECTED

​CARD_SHIPPED

​CARD_ACTIVATED

​CARD_STATUS_CHANGED

​AUTHORISATION_3DS_CHALLENGE

​交易事件

​CARD_TRANSACTION

​CARD_TRANSACTION_SETTLEMENT

​CARD_TRANSACTION_DEBT

​资金事件

​LOW_BALANCE

​BANK_TRANSFER_INFO

​BALANCE_CHANGE

​下一步

📄 正文

信封

事件总览（18 个）

组织事件

`ORGANIZATION_CREATED`

`ORGANIZATION_REJECTED`

`ORGANIZATION_STATUS_CHANGED`

员工事件

`CUSTOMER_CREATED`

`CUSTOMER_REJECTED`

`CUSTOMER_STATUS_CHANGED`

卡事件

`CARD_CREATED`

`CARD_REJECTED`

`CARD_SHIPPED`

`CARD_ACTIVATED`

`CARD_STATUS_CHANGED`

`AUTHORISATION_3DS_CHALLENGE`

交易事件

`CARD_TRANSACTION`

`CARD_TRANSACTION_SETTLEMENT`

`CARD_TRANSACTION_DEBT`

资金事件

`LOW_BALANCE`

`BANK_TRANSFER_INFO`

`BALANCE_CHANGE`

下一步