概览
3D Secure（3DS）是一种身份验证协议，用于为线上信用卡和借记卡交易提供额外的安全保护。它要求持卡人在完成交易前先向发卡机构进行身份验证，从而防止未授权用卡。3DS 身份验证模式
3DS 身份验证流程根据发卡机构的风险评估结果而有所不同，可能出现以下三种情况：- 无摩擦 3DS（Frictionless 3DS）：低风险交易自动完成身份验证，无需客户操作。系统通过 iframe 完成风险评估后直接完成支付，不要求 OTP。
- 挑战 3DS（Challenge 3DS）：高风险交易要求立即进行客户验证。客户直接被跳转至 ACS 身份验证页面输入 OTP 或完成生物特征验证。
- 混合 3DS（Mixed 3DS）：系统先通过 iframe 进行风险评估。如需进一步验证，客户随后被跳转至 ACS 页面输入 OTP。
集成要点：你无法预先判断会走哪种模式，这由发卡机构根据实时风险评估决定。你的集成必须通过检查 API 响应结构（next_action 字段）和 webhook 类型，动态处理所有场景。
集成步骤
集成流程
下图展示了基于 API 响应处理的 3DS 身份验证流程：步骤 1：在支付请求中启用 3DS
要启用 3DS 身份验证，在 Payment Intent 创建或确认请求中加入以下参数：步骤 2：处理 3DS 身份验证
创建启用 3DS 的 Payment Intent 后，根据响应按以下步骤处理：步骤 2.1：检查响应中的 next_action
响应状态会是 REQUIRES_CUSTOMER_ACTION。查看 next_action 字段以确定下一步：
情况 A：响应中存在 next_action.redirect_to_url
响应直接包含跳转 URL（不含 iframe），表示需要立即进入挑战流程。
- 从响应中提取
next_action.redirect_to_url.url - 将客户跳转至该 URL 完成 OTP 验证
- 等待最终 webhook：
acquiring.payment_intent.succeeded—— OTP 验证成功acquiring.payment_intent.failed—— OTP 验证失败或被取消
next_action.redirect_iframe
响应包含用于风险评估的 iframe，按以下步骤处理：
- 从响应中提取
next_action.redirect_iframe.iframe - 将 iframe 嵌入你的页面并执行（自动提交）
- 继续执行步骤 2.2 处理 webhook 响应
步骤 2.2：iframe 执行后处理 webhook（仅情况 B）
iframe 执行后，你会收到以下两种 webhook 之一： Webhook 情况 1：acquiring.payment_intent.succeeded
表示无摩擦身份验证成功，无需后续处理。
- 交易未经 OTP 即已完成
- 客户保持在你的页面
- 展示成功信息
acquiring.payment_intent.requires_action
表示风险评估后仍需挑战验证。
- 从 webhook payload 中提取
next_action.redirect_to_url.url - 将客户跳转至该 URL 完成 OTP 验证
- 等待最终 webhook：
acquiring.payment_intent.succeeded—— OTP 验证成功acquiring.payment_intent.failed—— OTP 验证失败或被取消
实现提示：你的集成必须动态处理两种响应类型（redirect_to_url与redirect_iframe），并处理 iframe 执行后的两种 webhook 场景。
注意：沙盒环境使用 OTP 0101。生产环境使用实际发送给持卡人的 OTP。
步骤 3：处理身份验证后流程
支付流程完成后：- 成功：客户会被跳转至初始请求中指定的
return_url。 - 失败：客户会被跳转至 UQ 支付失败页面。
沙盒测试
沙盒环境中的 3DS 测试，使用以下测试卡模拟不同身份验证模式：测试卡 —— 无摩擦 3DS
该卡模拟低风险交易，无需客户操作即可完成。
测试卡 —— 挑战 3DS
该卡模拟高风险交易，要求立即进行 OTP 验证。
测试卡 —— 混合 3DS
该卡模拟需先进行风险评估、再进入挑战验证的交易。