3DS 支付验证
3-Domain Secure™（3D 验证或 3DS）允许您在提交 Authorization 或 Pay 交易前对付款人进行身份验证，从而保护在线购买、防范信用卡欺诈。3DS 验证的工作原理是将付款人重定向到其输入之前注册的密码的发卡机构。
Mastercard Gateway 使用 Mastercard SecureCode™、Verified by Visa™、J/Secure™、American Express SafeKey™ 和 Diners Club ProtectBuy™ 支持 3DS 身份验证。
先决条件
- 您必须在收单行注册才能够使用 3DS
- 您必须通过 Mastercard Gateway 在商家配置文件中启用 3DS 计划。
3DS 付款人体验
此部分介绍使用 3DS 对付款人进行身份验证的购物网站的示例结账流。
成功身份验证的结账流如下所示：
- 付款人浏览您的购物网站，选择一个或多个产品，进入付款页，并选择使用支持 3DS 的卡支付。
- 检查 3DS 注册： 您要求 Mastercard Gateway 通过卡组织检查卡是否注册了 3DS
- 对付款人进行身份验证： 确认卡已注册后，您将付款人的浏览器重定向到其发卡机构的 3DS 身份验证页面。 付款人输入其 3DS 密码并提交信息。 发卡机构将认证结果返回给您。
- 处理 ACS 结果： 您要求 Mastercard Gateway 处理身份验证结果。Mastercard Gateway 向您提供从发卡机构接收的身份验证响应的详细信息。
- 在付款操作中使用 3DS 结果： 您提交付款进行处理
- 您向付款人显示订单确认页。
集成以使用 3DS 身份验证
此部分介绍如何集成到 Mastercard Gateway 以使用 3DS。
您可以通过在 Check 3DS Enrollment 请求中提供以下字段来检查卡是否已注册：
3DSecureId: 此身份验证的唯一识别码。您应该在所有后续操作中包括同一个识别码。3DSecure.authenticationRedirect.responseUrl: 您希望在完成 3DS 身份验证流程后将付款人重定向到的 URLorder.amount: 订单总额order.currency: 订单货币sourceOfFunds.provided.card、session.id或sourceOfFunds.token： 用于付款的卡的详细信息- （可选）
3DSecure.goodsDescription:您可以提供要购买的商品的简要描述。 如果发卡机构的访问控制服务器 (ACS) 支持，此描述将显示在向付款人呈现的身份验证页面。
Mastercard Gateway 在响应中提供注册检查结果：
3DSecure.xid: Mastercard Gateway 为 3DS 身份验证生成的唯一交易识别码。3DSecure.summaryStatus: 表明总体卡注册状态的汇总响应response.3DSecure.gatewayCode: 描述卡总体注册状态的详细响应
您应该查看 3DSecure.summaryStatus 以确定下一步该怎么做。 下表提供了汇总：
| 3DSecure.summaryStatus | 下一步 |
|---|---|
| CARD_ENROLLED | 卡已注册 3DS。 继续对付款人进行身份验证。 |
| CARD_NOT_ENROLLED | 卡未注册 3DS。 继续付款操作，在请求中包括 3DSecureID。 |
| CARD_DOES_NOT SUPPORT_3DS | 卡不支持 3DS，您不能继续进行 3DS 身份验证。 |
| AUTHENTICATION_NOT_AVAILABLE | 存在错误。 继续付款操作，在请求中包括 3DSecureID |
如果该卡已注册 (response.3DSecure.gatewayCode = CARD_ENROLLED)，则您应该将付款人的浏览器重定向到发卡机构的网站进行身份验证。 只需将 3DSecure.authenticationRedirect.simple.htmlBodyContent 中提供的内容返回给付款人的浏览器即可。
当身份验证流程在发卡机构网站完成后，发卡机构的访问控制服务器 (ACS) 将以发布到您在 Check 3DS Enrollment 请求中指定的响应 URL (3DSecure.authenticationRedirect.responseUrl) 的 HTTP 发布形式，将身份验证响应返回给您。
返回给您的支付身份验证响应 (PARes) 以 base64 编码值形式提供。 若要解码此值，将 PARes 传输到 Process ACS Result 操作中的 3DSecure.paRes 字段并提交该操作。Mastercard Gateway 在响应中提供身份验证结果：
3DSecure.summaryStatus: 指示总体身份验证状态的汇总响应response.3DSecure.gatewayCode: 描述身份验证状态的详细响应
您应该查看 response.3DSecure.summaryStatus 来确定要执行的下一个步骤。下表提供了汇总：
| 3DSecure.summaryStatus | 下一步 |
|---|---|
| AUTHENTICATION_SUCCESSFUL | 付款人成功通过身份验证。 继续付款操作，在请求中包括 3DSecureID。 |
| AUTHENTICATION_FAILED | 付款人未通过身份验证。 您不能继续付款操作。 此结果由组织规则决定。 |
| AUTHENTICATION_ATTEMPTED | 已尝试对付款人进行身份验证，但无法完成。 继续付款操作，在请求中包括 3DSecureID。 |
| AUTHENTICATION_NOT_AVAILABLE | 存在错误。 继续付款操作，在请求中包括 3DSecureID |
当 Check 3DS Enrollment 或 Process ACS 操作结果指示您可以继续付款时，您可以开始 Authorize 或 Pay 操作。 在请求中包括您在 Check 3DS Enrollment 操作中提供的 3DSecureId。 您无需在 3DSecure 参数组中包括任何参数，因为当您要求 Mastercard Gateway 处理身份验证结果时，其将使用 3DSecureId 查找存储的身份验证结果。Mastercard Gateway 将所需信息传送到收单行。
其他选项
在检查 3DS 前，您可以为动态货币兑换 (DCC) 提交费率报价请求来检索付款人货币以及使用该货币的订单金额。 如果付款人接受 DCC 出价，那么您必须在 Check 3DS Enrollment 请求中包括 DCC 信息。
用于重定向付款人以进行身份验证的表单所需的 HTML 可以使用两种页面生成方法之一生成：
Simple: Mastercard Gateway 生成 HTML 表单。 完整表单在 Check 3DS Enrollment 响应中返回。 这是默认选项。Customized: 您将使用 Check 3DS Enrollment 响应中提供的参数生成您自己的自定义 HTM 表单。
检查 3DS 注册操作的响应将包括所选选项所需的信息。
（可选）自定义简单表单
您可以通过在检查 3DS 注册请求中设置 3DSecure.authenticationRedirect.pageGenerationMode = SIMPLE 来定制生成的简单表单，然后指定一个或多个参数的值：
3DSecure.authenticationRedirect.simple.expectedHtmlEncoding3DSecure.authenticationRedirect.simple.redirectDisplayBackgroundColor3DSecure.authenticationRedirect.simple.redirectDisplayContinueButtonText3DSecure.authenticationRedirect.simple.redirectDisplayTitle
（可选）生成您自己的自定义表单
您可以通过在 Check 3DS Enrollment 请求中设置 3DSecure.authenticationRedirect.pageGenerationMode = CUSTOMIZED 来指定您将生成自己的表单。响应将包括以下参数：
3DSecure.authenticationRedirect.customized.acsUrl: 付款人可进行身份验证的发卡机构的访问控制服务器 (ACS) 的 URL。3DSecure.authenticationRedirect.customized.paReq: 发送给 ACS 以发起付款人身份验证的付款人身份验证请求 (PAReq) 消息。
在您的表单中包括这些值，以及身份验证完成后付款人将返回到的 URL。
下方显示了示例自定义表单：
<!-- Populate the form action attribute with the value returned in the 3DSecure.authenticationRedirect.customized.acsUrl response parameter -->
<form name="3dsRedirect" action="[3DSecure.authenticationRedirect.customized.acsUrl]" method="POST" accept-charset="UTF-8">
<!-- Populate the mandatory PaReq parameter with the value returned in the 3DSecure.authenticationRedirect.customized.paReq response parameter. -->
<input type="hidden" name="PaReq" value="[3DSecure.authenticationRedirect.customized.paReq]"/>
<!-- Populate the mandatory TermUrl value with the URL to which you want the payer returned when the authentication process has completed. This should be the same value as supplied in the 3DSecure.authenticationRedirect.responseUrl parameter to the CHECK_ENROLLMENT request. -->
<input type="hidden" name="TermUrl" value="https://merchant.com/3ds/return"/>
<!-- The ACS will echo the contents of the mandatory MD parameter when the payer is returned to the URL specified in the TermUrl parameter. You can use this parameter to establish a link between the ACS request and response. -->
<input type="hidden" name="MD" value="[mdvalue]"/>
<input type="submit" value="Click here to continue" class="button">
</form>
如果您使用外部 3DS MPI 对付款人进行身份验证，您必须在 Pay 或 Authorize 操作的 3DSecure 参数组中传递有关身份验证的信息。
有一个强制字段：
3DSecure.enrollmentStatus: 表示持卡人是否已注册 3DS。 此字段为强制字段。
其他字段是可选的，因为它们是否由外部 3DS MPI 提供给您取决于交易的身份验证状态：
3DSecure.authenticationStatus:指示付款人的 3DS 身份验证是否成功。3DSecure.authenticationToken: 发卡机构生成的可能在身份验证响应消息中返回给您的 base64 编码值。3DSecure.acsEci: 可能在身份验证响应消息中返回给您的电子商务指示符。3DSecure.xid: 3DS 身份验证的唯一交易识别码。
3DSecure.summaryStatus = AUTHENTICATION_ATTEMPTED，您应提供 3DSecure.authenticationToken。常见问题
Mastercard Gateway 在 response.3DSecure.gatewayCode 字段中提供身份验证状态的摘要。 如果您想派生用于处理付款的 3DS 字段的值，您可以从 response.3DSecure.gatewayCode 字段执行此操作。
| response.3DSecure.gatewayCode | 3DSecure.enrollmentStatus | 3DSecure.authenticationStatus | 提交付款操作 |
|---|---|---|---|
| CARD_ENROLLED | ENROLLED | - | （继续进行身份验证） |
| NOT_ENROLLED_NO_ERROR_DETAILS | NOT_ENROLLED | - | 是 |
| NOT_ENROLLED_ERROR_DETAILS_PROVIDED | NOT_ENROLLED | - | 是 |
| ENROLLMENT_STATUS_UNDETERMINED_NO_ERROR_DETAILS | ENROLLMENT_STATUS_UNDETERMINED | - | 是 |
| ENROLLMENT_STATUS_UNDETERMINED_ERROR_DETAILS_PROVIDED | ENROLLMENT_STATUS_UNDETERMINED | - | 是 |
| AUTHENTICATION_SUCCESSFUL | ENROLLED | AUTHENTICATION_SUCCESSFUL | 是 |
| AUTHENTICATION_ATTEMPTED | ENROLLED | AUTHENTICATION_ATTEMPTED | 是 |
| AUTHENTICATION_NOT_AVAILABLE_NO_ERROR_DETAILS | ENROLLED | AUTHENTICATION_NOT_AVAILABLE | 是 |
| AUTHENTICATION_NOT_AVAILABLE_ERROR_DETAILS_PROVIDED | ENROLLED | AUTHENTICATION_NOT_AVAILABLE | 是 |
| AUTHENTICATION_FAILED | ENROLLED | AUTHENTICATION_FAILED | 否（不允许） |
| MPI_PROCESSING_ERROR | ENROLLED | - | 是 |
| ACS_SESSION_TIMEOUT | ENROLLED | - | 是 |
| ERROR_PARSING_AUTHENTICATION_RESPONSE | ENROLLED | - | 否（失败） |
| INVALID_SIGNATURE_ON_AUTHENTICATION_RESPONSE | ENROLLED | - | 否（失败） |
| CARD_DOES_NOT_SUPPORT_3DS | - | - | 否（失败） |
| ERROR_PARSING_CHECK_ENROLLMENT_REQUEST | - | - | 否（失败） |
| INVALID_DIRECTORY_SERVER_CREDENTIALS | - | - | 是（无 3DS 数据） |
| ERROR_PARSING_CHECK_ENROLLMENT_RESPONSE | - | - | 是（无 3DS 数据） |
| ERROR_COMMUNICATING_WITH_DIRECTORY_SERVER | - | - | 是（无 3DS 数据） |
如果需要，您可以从 3DSecure.enrollmentStatus 派生 VERes.enrolled 值：
| VERes.enrolled | 3DSecure.enrollmentStatus |
|---|---|
| Y | ENROLLED |
| N | NOT_ENROLLED |
| U | ENROLLMENT_STATUS_UNDETERMINED |
您还可以从 3DSecure.authenticationStatus 派生 PAREs.status 值：
| PARes.status | 3DSecure.authenticationStatus |
|---|---|
| Y | AUTHENTICATION_SUCCESSFUL |
| N | AUTHENTICATION_FAILED |
| U | AUTHENTICATION_NOT_AVAILABLE |
| A | AUTHENTICATION_ATTEMPTED |
如果您在交易中提交了 3DS 详细信息，请在 Merchant Administration 中搜索订单或交易。 查看订单详细信息，然后选择查看身份验证详细信息的链接。
如果您想查看未继续付款的身份验证的详细信息（例如，身份验证失败），使用 Merchant Administration 中的“支付身份验证搜索”选项。
在 Merchant Administration 中查看身份验证详细信息时显示的身份验证状态代码可以映射到 response.3DSecure.gatewayCode。 请参见下表中的新代码：
| 支付客户端/虚拟支付客户端 | API | |
|---|---|---|
| 新代码 | 原代码 | response.3DSecure.gatewayCode |
| E | E | NOT_ENROLLED_NO_ERROR_DETAILS |
| Z | NOT_ENROLLED_ERROR_DETAILS_PROVIDED |
|
| C | C | CARD_DOES_NOT_SUPPORT_3DS |
| B | U | ENROLLMENT_STATUS_UNDETERMINED_NO_ERROR_DETAILS |
| V | ENROLLMENT_STATUS_UNDETERMINED_ERROR_DETAILS_PROVIDED |
|
| F | F | ERROR_PARSING_CHECK_ENROLLMENT_REQUEST |
| A | A | INVALID_DIRECTORY_SERVER_CREDENTIALS |
| W | U | ERROR_PARSING_CHECK_ENROLLMENT_RESPONSE |
| D | D | ERROR_COMMUNICATING_WITH_DIRECTORY_SERVER |
| I | I | MPI_PROCESSING_ERROR |
| P | P | ERROR_PARSING_AUTHENTICATION_RESPONSE |
| S | S | INVALID_SIGNATURE_ON_AUTHENTICATION_RESPONSE |
| T | T | ACS_SESSION_TIMEOUT |
| X | U | AUTHENTICATION_NOT_AVAILABLE_NO_ERROR_DETAILS |
| U | AUTHENTICATION_NOT_AVAILABLE_ERROR_DETAILS_PROVIDED |
|
| Y | Y | AUTHENTICATION_SUCCESSFUL |
| N | N | AUTHENTICATION_FAILED |
| M | M | AUTHENTICATION_ATTEMPTED |
| R | CARD_ENROLLED |
|
您可以通过使用 ACS 模拟器来测试您的集成以通过 Mastercard Gateway 执行 3DS 身份验证。 这允许您选择特定的 3DS 身份验证结果（在 3DSecure.authenticationStatus 的交易响应中返回）。
以下 3DS 支付验证计划支持测试：
- Mastercard SecureCode
- Verified by Visa
- American Express SafeKey
- J/Secure
- Diners ProtectBuy
要测试 3DS 支付验证功能：
- 在为测试商家配置文件提交
CHECK_3DS_ENROLLMENT请求时，使用已注册 3D 验证的测试卡（请参见特定“收单行”部分列出的卡）。 - 请使用
response.3DSecure.gatewayCode=CARD_ENROLLED检查是否收到响应。 - 使用
3DSecure.authenticationRedirect.simple.htmlBodyContent中提供的表单将付款人浏览器重定向到 ACS 模拟器页。ACS 模拟器将付款人浏览器重定向回您的网站并包含 PARes。
- 使用
3DSecure.paRes中的 PARes 提交PROCESS_ACS_RESULT请求。 - 使用 ID 通过后续交易请求（例如，
PAY或AUTHORIZE）的3DSecureId中提供的 Mastercard Gateway 进行此 3DS 支付验证。