> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 事件与数据结构

> 企业卡 18 个出站 Webhook 事件的信封字段、businessId 对应关系与各事件的 data 结构；配置与签名校验见 Webhook 配置。

## 📄 正文

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

> **前置条件**：先登记回调地址、准备好用 `SK` 复算 `X-Signature`。配置步骤与验签代码见 [Webhook 配置](./configuration)。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/PxXwc3LMXUdQj7w7/imgs/diagrams/corp-webhook-dispatch-light.svg?fit=max&auto=format&n=PxXwc3LMXUdQj7w7&q=85&s=d1869d912e87eb521dd8316d4340bf61" alt="Webhook 校验与按事件类型分发" width="714" height="396" data-path="imgs/diagrams/corp-webhook-dispatch-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/PxXwc3LMXUdQj7w7/imgs/diagrams/corp-webhook-dispatch-dark.svg?fit=max&auto=format&n=PxXwc3LMXUdQj7w7&q=85&s=0f02c9b954fd3da977eb05635c792fa5" alt="Webhook 校验与按事件类型分发" width="714" height="396" data-path="imgs/diagrams/corp-webhook-dispatch-dark.svg" />
</Frame>

## 信封

```json theme={null}
{
  "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 零时区。**取本次投递时刻，故同一事件的各次重试取值不同**    |

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

## 事件总览（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`      | 资金池余额不足预警                                 |

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

***

## 组织事件

### `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 拒绝原因           |

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

### `ORGANIZATION_STATUS_CHANGED`

镜像[更新组织限制项](../company-maintenance)，限制项变更落定后推送。

| 字段                   | 类型             | 说明       |
| :------------------- | :------------- | :------- |
| `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`

镜像[更新员工限制项](../employee-maintenance)。

| 字段                   | 类型             | 说明       |
| :------------------- | :------------- | :------- |
| `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 态） |

<Note>
  本事件**不含「激活」与「过期」**：激活单独发 `CARD_ACTIVATED`，过期当前无触发源。7 个卡状态见[管理卡片](../managing-cards)。
</Note>

### `AUTHORISATION_3DS_CHALLENGE`

业务流程与回传见 [3DS 挑战](../3ds-challenges)。

| 字段                    | 类型     | 说明                                          |
| :-------------------- | :----- | :------------------------------------------ |
| `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`（与请求签名同一把），与获取卡敏感信息同一套约定。

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

***

## 交易事件

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

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

### `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 | 商户类别码，四位数字                                                                                          |

```json theme={null}
{
  "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 | 商户类别码                                                                                                                                                                                                                                                                    |

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

### `CARD_TRANSACTION_DEBT`

进入欠款态时推送。

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

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

***

## 资金事件

### `LOW_BALANCE`

资金池余额低于阈值时预警。阈值设置见[公司维护](../company-maintenance)。

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

```json theme={null}
{
  "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`

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

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

## 下一步

* 回调地址登记、验签与重试约定：[Webhook 配置](./configuration)
* 3DS 挑战的接收与结果回传：[3DS 挑战](../3ds-challenges)
* 用查询接口做兜底对账：[账单与交易查询](../statements-and-transactions)