3DS 转发 - DCS Technical Documentation

📄 正文

无论您是交易所、钱包还是平台方，都可以使用自有应用中的短信、邮件或站内通知渠道完成持卡人的在线支付验证（3DS）。DCS 作为持牌发卡机构，负责与卡组织完成 3DS 协议交互、生成和校验验证码，并将验证所需的信息安全地转发给接入机构。 3DS（3D Secure）是在线支付的安全验证协议，会在交易过程中对持卡人进行额外身份核验，以降低盗刷风险。在合作伙伴自管模式下，DCS 提供 3 种 3DS 验证方式，接入机构可按自身希望掌控验证流程的程度，选择合适的方式。

三种模式速览

模式	谁发验证码	谁校验	接入机构要做的事	触发的 `flowsType`
模式一：DCS 直接发码	DCS	DCS	无需任何工作	不下发 Webhook
模式二：接入机构发码（OTP 代发）	接入机构	DCS	提供 Webhook 接收 OTP，解密后发给用户	`OTP_DELEGATE`
模式三：引导用户到接入机构验证（OOB）	接入机构（通过自有应用或其他渠道引导）	接入机构，再将结果返回 DCS	接收 Webhook 通知、引导用户认证并返回结果	`OOB`

采用哪种模式由您的卡 Program 配置决定。配置 3DS 模式：DCS；接入对接：接入机构。如需变更，请联系 DCS 团队。

3DS 转发整体流程

下图为 3DS 验证请求在各方之间转发的整体往返：DCS 收到卡组织的验证请求后转发给接入机构，接入机构（按所选模式）完成验证并原路返回结果，DCS 再以 Webhook 通知挑战状态更新。具体由谁发码、由谁判定，见下方各模式详解。

模式一：DCS 直接发送验证码

DCS 直接给持卡人发送短信/邮件验证码并完成校验。这种模式下接入机构无需做任何额外工作，DCS 自动处理验证码的生成、发送与核验，不会下发 3DS Webhook。适合：尚未自建消息通道、希望最快上线的接入机构。

模式二：接入机构发送验证码（OTP_DELEGATE）

由接入机构用自己的渠道把验证码发给持卡人，DCS 负责校验。这种模式下，接入机构需提供 Webhook 接收 DCS 推送的 OTP，解密后转发给用户。

Webhook 字段（3DS 挑战通知）

3DS 相关 Webhook 的类型为 AUTHORISATION_3DS_CHALLENGE，通过 flowsType 区分模式。模式二下 flowsType=OTP_DELEGATE。

字段	类型	说明
`challengeId`	string	3DS 挑战 ID
`status`	string	挑战状态：`INIT` / `NOTICED` / `RECEIVED` / `APPROVED` / `REJECTED`
`cardId`	string	卡 ID
`expiryTime`	string	挑战过期时间
`currency`	string	发起交易的币种
`amount`	number	发起交易的金额
`merchantId`	string	商户 ID
`merchantName`	string	商户名称
`merchantCountry`	string	商户国家
`mcc`	string	商户类别码
`flowsType`	string	认证流程类型：`OOB` / `OTP_DELEGATE`
`challengeMethodType`	string	挑战方法类型：`DELEGATE_SCA_V1` / `SMS_OTP` / `EMAIL_OTP`
`otpPasscode`	string	OTP 验证码（AES-GCM 加密），仅 `flowsType=OTP_DELEGATE` 时有值
`phoneNumber`	string	持卡人手机号（AES-GCM 加密），仅 `flowsType=OTP_DELEGATE` 时有值
`email`	string	持卡人邮箱（AES-GCM 加密），仅 `flowsType=OTP_DELEGATE` 时有值
`iv`	string	AES-GCM 加密用的 IV（Base64 编码），仅 `flowsType=OTP_DELEGATE` 时有值

Webhook 的整体投递、外层包裹与签名校验，请见 Webhook 事件与数据结构。

解密 OTP（接入机构）

otpPasscode、phoneNumber、email 使用接入机构的 secretKey，以 AES-GCM 模式加密；Webhook 中随附 iv。接入机构收到后用 secretKey + iv 解密。

算法：AES-128-GCM（NoPadding）
密钥：接入机构的 secretKey，Base64 编码
IV：Webhook 的 iv 字段，Base64 编码，12 字节
认证标签（Auth Tag）：128 位，附在密文末尾
密文格式：Base64 编码（解码后为 ciphertext + authTag）

import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class AesGcmDecryptor {

    public static String decrypt(String base64Ciphertext, String base64Key, String base64IV) {
        byte[] key = Base64.getDecoder().decode(base64Key);
        byte[] iv = Base64.getDecoder().decode(base64IV);
        byte[] ciphertext = Base64.getDecoder().decode(base64Ciphertext);

        SecretKeySpec secretKey = new SecretKeySpec(key, "AES");
        GCMParameterSpec spec = new GCMParameterSpec(128, iv);

        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(Cipher.DECRYPT_MODE, secretKey, spec);

        byte[] plaintext = cipher.doFinal(ciphertext);
        return new String(plaintext, StandardCharsets.UTF_8);
    }
}

// 使用示例
String otpPasscode = decrypt(webhook.getOtpPasscode(), secretKey, webhook.getIv());
String phoneNumber = decrypt(webhook.getPhoneNumber(), secretKey, webhook.getIv());
String email       = decrypt(webhook.getEmail(), secretKey, webhook.getIv());

模式二中校验仍由 DCS 完成：接入机构只负责把解密后的验证码发送给用户，无需回传验证结果；最终结果通过 status=APPROVED/REJECTED 的 Webhook 通知。

模式三：引导用户到接入机构验证（OOB）

OOB（Out-Of-Band，带外认证）模式下，接入机构通过自有应用或其他渠道引导持卡人完成认证（如生物识别、应用内确认），由接入机构判定是否通过，再将结果返回 DCS。此模式下 Webhook 的 flowsType=OOB、challengeMethodType=DELEGATE_SCA_V1，且不会发送 otpPasscode / phoneNumber / email / iv。

回传认证结果（接入机构）

接入机构判定完成后，调用 POST /open-api/3ds-challenge/v1/authenticate 把结果回传给 DCS。 最小请求：

{
  "challengeId": "<Webhook 推送的 challengeId>",
  "approveStatus": "APPROVE"
}

请求字段：

字段	类型	必填	说明
`challengeId`	string	是	发起交易前的 3DS 挑战 ID（来自 OOB Webhook）；最大 50
`approveStatus`	string	是	挑战操作：`APPROVE` / `REJECT`；最大 20

响应： 所有 /open-api/ 接口共用统一响应结构 { code, message, messageDetail, data }。成功时 data 回显挑战当前状态：

{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "challengeId": "CHL_1a2b...",
    "status": "APPROVED",
    "cardId": "CARD_8f3a...",
    "expiryTime": "2026-06-17T08:05:00Z",
    "currency": "USD",
    "amount": 100.00,
    "merchantId": "M_001",
    "merchantName": "Acme Store",
    "merchantCountry": "SG",
    "mcc": "5732"
  }
}

响应字段	说明
`challengeId`	3DS 挑战 ID
`status`	挑战状态：`INIT` / `NOTICED` / `RECEIVED` / `APPROVED` / `REJECTED`
`cardId`	卡 ID
`expiryTime`	挑战过期时间
`currency`	发起交易的币种
`amount`	发起交易的金额
`merchantId`	商户 ID
`merchantName`	商户名称
`merchantCountry`	商户国家
`mcc`	商户类别码

响应结构说明：业务成败请以 code 为准（如 SYS_SUCCESS；错误码说明见授权拒绝与错误码）；message 为简要说明；messageDetail 是可选的展示对象（含 message / title / type / icon / action / linkTitle / linkUrl），仅供前端引导，不应作为判断成败的依据。

请在 expiryTime 之前回传结果。该时限来自 3DS 厂商下发的挑战有效期；过期未回传时，DCS 会把挑战置为 REJECTED，不会自动批准。

接入要点

Content-Type：所有 /open-api/ 请求请显式设置 Content-Type: application/json。
鉴权：调用 /open-api/3ds-challenge/v1/authenticate 与接收 Webhook 的签名校验，遵循鉴权指南。
Webhook 接口：模式二、模式三都要求接入机构预先配置可接收 AUTHORISATION_3DS_CHALLENGE 的 Webhook 地址（由接入机构提供给 DCS）。
模式三回传时限：必须在厂商下发的 expiryTime 前回传；逾期挑战置为 REJECTED。
OTP 失败处理：模式二同步等待接入机构 Webhook 最多 7 秒。超时、返回失败、解密失败或发送失败时，不会重发，也不会改由 DCS 代发，当前挑战直接置为 REJECTED。接入机构需在 7 秒内完成解密和发送，并同步返回 phoneNumberTail / email。

下一步

3DS 验证通过后，交易进入授权环节。前往授权了解授权决策如何转发给接入机构，再看授权与清算理解资金的冻结与最终清算。

​📄 正文

​三种模式速览

​3DS 转发整体流程

​模式一：DCS 直接发送验证码

​模式二：接入机构发送验证码（OTP_DELEGATE）

​Webhook 字段（3DS 挑战通知）

​解密 OTP（接入机构）

​模式三：引导用户到接入机构验证（OOB）

​回传认证结果（接入机构）

​接入要点

​下一步

📄 正文

三种模式速览

3DS 转发整体流程

模式一：DCS 直接发送验证码

模式二：接入机构发送验证码（OTP_DELEGATE）

Webhook 字段（3DS 挑战通知）

解密 OTP（接入机构）

模式三：引导用户到接入机构验证（OOB）

回传认证结果（接入机构）

接入要点

下一步