> ## 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.

# 3DS 挑战处理

> AUTHORISATION_3DS_CHALLENGE 事件的全字段与 OOB / OTP_DELEGATE 两类载荷示例；三种认证模式的处理分工；OOB 模式经 authenticate 接口回传验证结果，重复回传幂等。

## 📄 正文

持卡人线上消费触发 3DS 认证时，DCS 将挑战转发给合作伙伴处理：推送 Webhook `AUTHORISATION_3DS_CHALLENGE`，您按对接时配置的模式参与验证或发码（模式按卡 BIN 段在发卡侧配置）。本页给出挑战事件的全字段与两类载荷示例、三种模式各自要做什么，以及 OOB 模式唯一的回传接口怎么调。

## AUTHORISATION\_3DS\_CHALLENGE：挑战事件

事件 `data` 字段如下：

| 字段                                                            | 说明                                                              |
| ------------------------------------------------------------- | --------------------------------------------------------------- |
| `challengeId`                                                 | 挑战 ID，OOB 回传时原样传入 authenticate 接口                               |
| `status`                                                      | 挑战状态（下发时为 `INIT`）                                               |
| `cardId` / `organizationId`                                   | 触发挑战的卡与所属公司                                                     |
| `expiryTime`                                                  | 挑战过期时间，格式 `yyyy-MM-dd'T'HH:mm:ssXXX`                            |
| `currency` / `amount`                                         | 交易币种（ISO 4217 数字代码，如 `840`）与金额                                  |
| `merchantId` / `merchantName` / `merchantCountryCode` / `mcc` | 商户信息                                                            |
| `challengeFlowType`                                           | 挑战模式：`OOB` / `OTP_DELEGATE`                                     |
| `challengeMethodType`                                         | 挑战方法（如 `DELEGATE_SCA_V1` / `SMS_OTP`）                           |
| `encryptedOtpPasscode`                                        | 验证码密文（AES-GCM，Base64），**仅 OTP\_DELEGATE 携带**                    |
| `phoneNumber` / `email`                                       | 持卡人手机号 / 邮箱密文（AES-GCM，Base64），仅 OTP\_DELEGATE 携带，未配置的一项为 `null` |
| `iv`                                                          | AES-GCM 初始向量（Base64），本事件内各密文字段共用                                |

**OOB 挑战载荷示例**（只含基本交易信息，验证在您的 App 内完成）：

```json theme={null}
{
  "challengeId": "5211234567890123456",
  "status": "INIT",
  "cardId": "5136759791164443137",
  "organizationId": "1276574398205403138",
  "expiryTime": "2026-08-13T19:31:30+08:00",
  "currency": "840",
  "amount": 129.99,
  "merchantId": "MCT00001",
  "merchantName": "EXAMPLE ONLINE STORE",
  "merchantCountryCode": "IE",
  "mcc": "5732",
  "challengeFlowType": "OOB",
  "challengeMethodType": "DELEGATE_SCA_V1"
}
```

**OTP\_DELEGATE 挑战载荷示例**（额外携带验证码与触达方式的密文）：

```json theme={null}
{
  "challengeId": "5211234567890123457",
  "status": "INIT",
  "cardId": "5136759791164443137",
  "organizationId": "1276574398205403138",
  "expiryTime": "2026-08-13T19:31:30+08:00",
  "currency": "344",
  "amount": 500.00,
  "merchantId": "MCT00002",
  "merchantName": "EXAMPLE TRAVEL",
  "merchantCountryCode": "HK",
  "mcc": "4722",
  "challengeFlowType": "OTP_DELEGATE",
  "challengeMethodType": "SMS_OTP",
  "encryptedOtpPasscode": "kX9…（AES-GCM 密文，Base64）",
  "phoneNumber": "aB3…（AES-GCM 密文，Base64）",
  "email": null,
  "iv": "R4nd0mIVBase64=="
}
```

## 三种模式的处理分工

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/corp-3ds-challenges-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=dc404a96e3d31e2d1a83e8c8fcb643fd" alt="三种 3DS 挑战模式的处理分工" width="446" height="786" data-path="imgs/diagrams/corp-3ds-challenges-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/corp-3ds-challenges-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=5c8f0fe111ccea91a9c5825ccd88da42" alt="三种 3DS 挑战模式的处理分工" width="446" height="786" data-path="imgs/diagrams/corp-3ds-challenges-dark.svg" />
</Frame>

收到挑战事件后，按您对接时配置的模式处理：

| 模式             | 挑战触达                                   | 挑战处理方                                                                    |
| -------------- | -------------------------------------- | ------------------------------------------------------------------------ |
| 发卡行 OTP        | DCS 直接向持卡人发送验证码（Email / SMS）           | 整个挑战处理闭环在 DCS 内完成，合作伙伴零感知，不会收到挑战事件                                       |
| `OTP_DELEGATE` | DCS 推送 Webhook 给合作伙伴，内含验证码及邮箱 / 手机号等密文 | 合作伙伴解密后，使用自有渠道将验证码发送给持卡人；持卡人在挑战页输入完成，**无需回传结果**                          |
| `OOB`          | DCS 推送 Webhook 给合作伙伴，内含基本交易信息          | 合作伙伴向持卡人 App 推送验证消息 → 持卡人在 App 内完成验证 → 合作伙伴调用 authenticate 接口回传验证结果给 DCS |

<Warning>
  **挑战有效期约 300 秒**（以事件中的 `expiryTime` 为准），超时按拒绝处理。结果确认接口仅用于 OOB 模式。
</Warning>

## OOB 回传：authenticate 接口

**`POST /open-api-corp/card3ds/v1/authenticate`**——挑战结果确认，把持卡人验证结果回传 DCS，**仅 OOB 链路可调**。

**请求参数**

| 字段            | 类型     | 必填 | 说明                                                           |
| ------------- | ------ | -- | ------------------------------------------------------------ |
| `challengeId` | String | 是  | ≤64；挑战 ID，取自挑战事件的 `data.challengeId`                         |
| `action`      | String | 是  | ≤16；持卡人验证结果，枚举全集：`APPROVE`（持卡人验证通过）/ `REJECT`（持卡人拒绝 / 验证不通过） |
| `operateTime` | String | 否  | ≤32；持卡人操作时间，格式 `yyyy-MM-dd'T'HH:mm:ssXXX`；审计用，原样记录不做服务端兜底    |

**响应 data**

| 字段            | 类型     | 说明                           |
| ------------- | ------ | ---------------------------- |
| `challengeId` | String | 挑战 ID（回显请求传入的 `challengeId`） |
| **请求示例**      |        |                              |

```json theme={null}
// 场景一：OOB 挑战——回传持卡人验证结果（本接口仅 OOB 链路可调）
{
  "challengeId": "5185740066240790531",
  "action": "APPROVE",
  "operateTime": "2026-08-19T10:30:00+08:00"
}
// 场景二：OTP_DELEGATE 挑战无回传动作——误调本接口将返回 CARD_3DS_CHALLENGE_NOT_FOUND（见响应示例场景二）
```

**响应示例**

```json theme={null}
// 场景一：OOB 挑战受理成功（重复回传同一结果时幂等返回，与首次响应相同）
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "challengeId": "5185740066240790531"
  }
}
// 场景二：对 OTP_DELEGATE 挑战误调本接口（无回传路径，被拒）
{
  "code": "CARD_3DS_CHALLENGE_NOT_FOUND",
  "message": "challenge not found",
  "data": null
}
```

**错误码**

| 错误码                            | 说明                                                                 |
| ------------------------------ | ------------------------------------------------------------------ |
| `CARD_3DS_CHALLENGE_NOT_FOUND` | 挑战不存在 / 不属本合作伙伴 / 非 OOB 挑战（如对 OTP\_DELEGATE 挑战误调本接口）——三种情形同码，不差分暴露 |

<Note>
  **幂等**：对同一 `challengeId` 重复回传同一结果，接口幂等返回，响应与首次相同——重试无需做防重设计。
</Note>

<Info>
  **合规提示 · 香港金融管理局 3DS 条规**：根据香港金融管理局（HKMA）2025 年 4 月 14 日发布的要求，网上信用卡交易须通过银行 App 完成验证。金管局在 2024 年 8 月 1 日的新闻稿中，已将该要求同步适用于 32 家银行及 10 家储值支付工具（SVF）营运机构。合作伙伴如面向香港持卡人，建议采用 OOB（App 内认证）模式以满足该合规方向。参考：[HKMA《New Anti-Digital Fraud Measures: E-Banking Security ABC》](https://brdr.hkma.gov.hk/eng/doc-ldg/docId/getPdf/20250411-1-EN/20250411-1-EN.pdf)、[香港银行公会（HKAB）声明](https://www.hkab.org.hk/en/news/press-release/318)。
</Info>

## 下一步

* 挑战通过后的授权与清算主线：[实时授权与清算](./realtime-authorization)
* 交易事件全景与授权语义：[交易管理 · 概述](./authorization-and-3ds)