3DS 集成指南 - 方式 2

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

​

概览

3D Secure（3DS）是一种身份验证协议，用于为线上信用卡和借记卡交易提供额外的安全保护。它要求持卡人在完成交易前先向发卡机构进行身份验证，从而防止未授权用卡。

​

3DS 身份验证模式

3DS 身份验证流程根据发卡机构的风险评估结果而有所不同，可能出现以下三种情况：

1. 无摩擦 3DS（Frictionless 3DS）：低风险交易自动完成身份验证，无需客户操作。系统通过 iframe 完成风险评估后直接完成支付，不要求 OTP。
2. 挑战 3DS（Challenge 3DS）：高风险交易要求立即进行客户验证。客户直接被跳转至 ACS 身份验证页面输入 OTP 或完成生物特征验证。
3. 混合 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），表示需要立即进入挑战流程。

1. 从响应中提取 next_action.redirect_to_url.url
2. 将客户跳转至该 URL 完成 OTP 验证
3. 等待最终 webhook：
   • acquiring.payment_intent.succeeded —— OTP 验证成功
   • acquiring.payment_intent.failed —— OTP 验证失败或被取消

情况 B：响应中存在 next_action.redirect_iframe 响应包含用于风险评估的 iframe，按以下步骤处理：

1. 从响应中提取 next_action.redirect_iframe.iframe
2. 将 iframe 嵌入你的页面并执行（自动提交）
3. 继续执行步骤 2.2 处理 webhook 响应

​

步骤 2.2：iframe 执行后处理 webhook（仅情况 B）

iframe 执行后，你会收到以下两种 webhook 之一： Webhook 情况 1：acquiring.payment_intent.succeeded 表示无摩擦身份验证成功，无需后续处理。

• 交易未经 OTP 即已完成
• 客户保持在你的页面
• 展示成功信息

Webhook 情况 2：acquiring.payment_intent.requires_action 表示风险评估后仍需挑战验证。

1. 从 webhook payload 中提取 next_action.redirect_to_url.url
2. 将客户跳转至该 URL 完成 OTP 验证
3. 等待最终 webhook：
   • acquiring.payment_intent.succeeded —— OTP 验证成功
   • acquiring.payment_intent.failed —— OTP 验证失败或被取消

实现提示：你的集成必须动态处理两种响应类型（redirect_to_url 与 redirect_iframe），并处理 iframe 执行后的两种 webhook 场景。

注意：沙盒环境使用 OTP 0101。生产环境使用实际发送给持卡人的 OTP。

​

步骤 3：处理身份验证后流程

支付流程完成后：

1. 成功：客户会被跳转至初始请求中指定的 return_url。
2. 失败：客户会被跳转至 UQ 支付失败页面。

​

沙盒测试

沙盒环境中的 3DS 测试，使用以下测试卡模拟不同身份验证模式：

​

测试卡 —— 无摩擦 3DS

该卡模拟低风险交易，无需客户操作即可完成。

​

测试卡 —— 挑战 3DS

该卡模拟高风险交易，要求立即进行 OTP 验证。

​

测试卡 —— 混合 3DS

该卡模拟需先进行风险评估、再进入挑战验证的交易。