3DS 认证

3DS 认证

3D Secure 2 是一种身份验证协议，可为无卡 (CNP) 交易提供额外的验证。 我们建议您使用 3D Secure 2 在线上交易中进行消费者身份验证，并利用责任转移降低风险。

TIP

EVO Payment 支持您在授权（Payment）或者绑卡（PaymentMethod）流程中加入 3DS 认证。同时 EVO Payment 也支持您在已经获取到一笔交易的 3DS 认证结果后，仅通过 EVO Payment 发起授权。同时 EVO Payment 还支持您仅通过 EVO Payment 进行 3DS 认证获取 3DS 认证结果而不发起授权。

3DS 模式

符合 3D Secure 2 的交易可以触发平滑认证流程或需要进行额外的挑战认证流程，具体是否需要额外的挑战流程取决于发卡行的要求。

3DS 平滑模式

在平滑模式流程中，收单机构、发卡行和卡组织通过收集消费者的设备指纹信息进行交易风险判断，如果验证通过，则无需进一步与消费者交互。

3DS 挑战模式

如果在平滑模式认证流程中发卡行认为交易存在风险，发卡行会触发额外的认证流程，用户会被重定向到发卡行的页面进行额外的身份认证。发卡行可能通过生物识别、双因素身份验证、短信验证码或密码等对消费者的身份进行进一步的验证。

3DS 集成说明

EVO Payment 提供两种 3DS 集成模式供您选择，您可以根据自身需求选择合适您的方式集成 3DS 功能，下面为您介绍两种集成方式的区别，以及各自的集成流程。

集成模式	authentication.authenticationType	优缺点
Redirect for 3D Secure 2	threeDSPage	优点：集成过程简单 缺点：跳转次数多用户体验一般
Native for 3D Secure 2	threeDS	优点：用户体验好，平滑模式下用户无感 缺点：集成过程复杂

Redirect for 3D Secure 2 集成流程

在您调用 POST Payment 接口或 POST PaymentMethod 接口时均可以添加额外的参数在原始流程中触发 3DS 认证流程。

主要流程如下：

1. 在调用 Payment 接口或 PaymentMethod 接口时额外添加以下参数，字段详情参考 API 文档：

   • authentication.authenticationOnly：用来表明是否仅进行 3DS 认证，当前场景默认填 false，如果填 true EVO Payment 将只会进行 3DS 认证，不会发起后续的授权，并将 3DS 结果返回给您（本字段仅适用于 Payment 接口）。
   • authentication.authenticationMethod：表明方式方式的字段，固定值 CILAuth。
   • authentication.authenticationType：表明认证模式的字段，固定值 threeDSPage。
   • authentication.returnUrl：认证结束后回调地址，根据您的业务需求设定。
   • authentication.threeDS.deviceType：表明消费者设备类型的字段。

2. 检查 EVO Payment 应答中的 payment.status 或 paymentMethod.status 字段内容。如果字段的值为 Verifying 则表示交易创建成功，等待对消费者进行 3DS 认证。然后您需要查看 result.action 字段内容，然后根据 result.action 字段进行后续处理。

   TIP

   result.action 的处理说明：

   result.action	解释
   RedirectShopper	需要商户将前端页面重定向至 authentication.threeDS.redirectUrl 字段返回的地址

3. 通常在 Redirect for 3D Secure 2 集成流程中，您收到的 result.action 字段内容将会是 RedirectShopper。此时您需要使用 GET 的方式将您的消费者重定向到 authentication.threeDS.redirectUrl 字段返回的地址。

Note

此时消费者将被重定向到 EVO Payment 的 3DS 认证页面，然后 EVO Payment 将与消费者和发卡行共同完成 3DS 认证的全部流程，在流程结束后 EVO Payment 将会把消费者重定向到 authentication.returnUrl。

4. 消费者将在 10 分钟内被 EVO Payment 通过 GET 的方式重定向到您的 authentication.returnUrl，同时 EVO Payment 将会在您的重定向地址后以参数的形式添加以下两个字段。

   • merchantTransID 可以用来匹配您的初始请求
   • status 可以用来判断 3DS 流程是否结束

   INFO

   回调请求样例：https://www.yourwebsite.com?merchantTransID=T12345678&status=finished

   如果 status 的值为 finished，需要您调用 GET Payment 或 GET PaymentMethod 来查询交易结果。

   如果 10 分钟内没有收到回调请求，或者 status 的值不是 finished，您可以认为 3DS 认证失败，您调同样可以调用 GET Payment 或 GET PaymentMethod 接口来查询失败详情。

   CAUTION

   回调地址中的 status = finished 不能表示最终的交易结果， status 的作用仅供您处理前端流程时使用，最终的交易状态需要您通过查询或者异步通知获取。

Native for 3D Secure 2 集成流程

在您调用 POST Payment 接口或 POST PaymentMethod 接口时均可以添加额外的参数在原始流程中触发 3DS 认证流程。

主要流程如下：

1. 收集消费者浏览器信息，并将其放入 browserInfo 结构体，您需要收集的浏览器信息如下，字段详情参考 API 文档：

   • acceptHeader
   • colorDepth
   • javaEnabled
   • javaScriptEnabled
   • language
   • screenHeight
   • screenWidth
   • timeZoneOffset
   • userAgent

2. 在调用 POST Payment 接口或 POST PaymentMethod 接口时额外添加以下参数，字段详情参考 API 文档：

   • authentication.authenticationOnly：用来表明是否仅进行 3DS 认证，当前场景默认填 false，如果填 true EVO Payment 将只会进行 3DS 认证，不会发起后续的授权，并将 3DS 结果返回给您（本字段仅适用于 Payment 接口）。
   • authentication.authenticationMethod：表明方式方式的字段，固定值 CILAuth。
   • authentication.authenticationType：表明认证模式的字段，固定值 threeDS。
   • authentication.returnUrl：接收发卡行返回的认证结果。
   • authentication.threeDS.deviceType：表明消费者设备类型的字段。
   • browserInfo：您在第一步中收集到的消费者浏览器信息。

3. 检查 EVO Payment 应答中的 payment.status 或 paymentMethod.status 字段内容。如果字段的值为 Verifying 则表示交易创建成功，等待对消费者进行 3DS 认证。然后您需要查看 result.action 字段内容，然后根据 result.action 字段进行后续处理。

   TIP

   result.action 的处理说明：

   result.action	解释
   IdentifyShopper	需要商户将前端页面重定向至 authentication.threeDS.redirectUrl 字段返回的地址
   ChallengeShopper	需要商户在前端页面通过 POST 的方式，将 authentication.threeDS.redirectData.creq 参数发送至 authentication.threeDS.redirectUrl 字段返回的地址

4. 如果您收到的 result.action 字段内容是 IdentifyShopper，此时您需要执行 3D Secure 2 设备指纹识别。

   TIP

   在这一步中如果您收到的 result.action 字段内容是 ChallengeShopper，请直接跳到第 5 步。

   a. 在 iframe 中发起用户浏览器指纹信息验证

   在消费者的浏览器中渲染一个隐藏的 iframe，然后在 iframe 中使用 POST 的方式访问 authentication.threeDS.redirectUrl，同时在请求参数中添加 authentication.threeDS.redirectData.threeDSMethodData。

   CAUTION

   请保持 POST 请求中字段名称的字母大小写与 EVO Payment 响应返回的 authentication.threeDS.redirectData 结构体中的参数名称一致。

   样例： 商户通过 form POST 向authentication.threeDS.redirectUrl 发送的threeDSMethodData

   <form method="POST" action="{authentication.threeDS.redirectUrl}" id="IdentifyShopper" target="NAME_OF_YOUR_IFRAME">
   <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9ZT1VSX0NPTVBBTlkuY29tL1JFVFVSTlVSTCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiN2MzOWJkOTYtOThlZS00N2IwLTgzYWYtNjMwNjE2NmE3MDE4In0=" />
   </form>

   b. 等待指纹验证结果返回到 authentication.returnUrl

   发卡行将在从发起设备指纹验证请求起的 10 秒种内响应，您可以在 authentication.returnUrl 中添加 merchantTransID 来匹配原始请求，然后将在后续的 PUT 请求中将 threeDSComplnd 设置为 Y，然后进行后续处理。

   TIP

   如果您在之前的 POST 请求中的authentication.returnUrl中未指定merchantTransID，那么您也可以对 base64 编码的threeDSMethodData进行解码，获取并存储 threeDSServerTransID 以用于对发卡行应答的匹配。因为发卡行会在应答中添加threeDSMethodData，其中threeDSServerTransID与请求时一致。

   如果发卡行在 10 秒内没有得到任何响应，则可以将threeDSComplnd 设置为 N，然后准备进行后续处理。

   样例： 发卡行向authentication.returnUrl 发送的threeDSMethodData

   <form method="POST" action="{authentication.returnUrl}" id="IdentifyShopper" target="NAME_OF_YOUR_IFRAME">
   <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjdjMzliZDk2LTk4ZWUtNDdiMC04M2FmLTYzMDYxNjZhNzAxOCJ9" />
   </form>

   c. 将指纹验证结果发送给 EVO Payment

   您需要调用 PUT Payment 接口或 PUT PaymentMethod 接口，然后在接口中添加以下字段

   • authentication.threeDS.redirectData.threeDSComplnd：指纹验证的结果标识。

   d. 处理 EVO Payment 返回的结果

   如果在 EVO Payment 的应答中没有出现 result.action 字段，那么需要您根据 payment.status 或 paymentMethod.status 字段的值来判断最终的交易结果。否则您将需要继续执行 result.action 中的内容来继续完成 3DS 认证。

5. 如果您收到的 result.action 字段内容是 ChallengeShopper，此时您需要将消费者重定向到发卡行的页面进行进一步的身份验证 。

   a. 在 iframe 中发起 CReq（ChallengeRequest）验证

   在消费者的浏览器中渲染一个隐藏的 iframe，然后在 iframe 中使用 POST 的方式访问 authentication.threeDS.redirectUrl，同时在请求参数中添加 authentication.threeDS.redirectData.creq。

   样例： 商户通过 form POST 向authentication.threeDS.redirectUrl 发送的 CReq 请求

   <form method="POST" action="{authentication.threeDS.redirectUrl}" id="ChallengeShopper" target="NAME_OF_YOUR_IFRAME">
   <input name="creq" value="eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI3YzM5YmQ5Ni05OGVlLTQ3YjAtODNhZi02MzA2MTY2YTcwMTgiLCJhY3nUcmFuc0lEIjoiMTE4ZDNiNjEtYjU5Ny00Nzg2LTg1ZWMtNzA0Mzc3ZDhjMWU4IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0=" />
   </form>

   CAUTION

   1. 请保持 POST 请求中字段名称的字母大小写与 EVO Payment 响应返回的authentication.threeDS.redirectData结构体中的参数名称一致。

   2. 您也可以在 CReq 请求中添加threeDSSessionData字段，如果您上送了本字段，发卡行在 Cres 中将原样返回。

      字段名称	长度/格式
      threeDSSessionData	长度：最大 1024 字节 格式：字母数字 Base64url 编码。

   b. 等待 Cres 验证结果返回到 authentication.returnUrl

   发卡行将在从发起 Creq 验证请求起的 10 分钟内响应，您可以使用您设置在 authentication.returnUrl 中的 merchantTransID 来匹配原始请求，然后将 threeDSFinished 设置为 Y，同时记录响应中的 cres 字段的值，然后准备进行后续处理。

   TIP

   如果您在之前的 POST 请求中的 authentication.returnUrl 中未指定merchantTransID，您也可以在 Creq 请求中添加threeDSSessionData用于对 Cres 应答的比配

   如果发卡行在 10 分钟内没有得到任何响应，或者在响应中没有找到 cres 字段，则可以将threeDSFinished 设置为 N，然后准备进行后续处理。

   c. 将 Cres 验证结果发送给 EVO Payment

   您需要调用 PUT Payment 接口或 PUT PaymentMethod 接口，然后在接口中添加以下字段

   • authentication.threeDS.redirectData.threeDSFinished：Cres 验证的结果标识。
   • authentication.threeDS.redirectData.cres：Cres 验证的结果参数。

   d. 处理 EVO Payment 返回的结果

   如果在 EVO Payment 的应答中没有出现 result.action 字段，那么需要您根据 payment.status 或 paymentMethod.status 字段的值来判断最终的交易结果。否则您将需要继续执行 result.action 中的内容来继续完成 3DS 认证。

6. 如果您没有收到来自 EVO Payment 的应答报文，则需要您调用 GET Payment 或 GET PaymentMethod 来查询交易结果。当收到查询应答时，您同样也需要通过 payment.status 或 paymentMethod.status 字段内容来判断交易结果。如果交易失败，您需要通过 payment.failureCode 以及 payment.failureReason 来查看交易失败原因。

自有 3DS 结果进行支付

EVO Payment 支持您在已经获取到一笔交易的 3DS 认证结果后，仅通过 EVO Payment 发起授权。您可以在普通的授权交易中使用该功能，在 POST Payment 请求中额外添加以下参数：

• authentication.authenticationOnly：固定值 false。
• authentication.authenticationMethod：固定值 SelfAuth。
• authentication.threeDS.mpiData：包含了 3DS 结果的结构体。

后续流程与普通的授权一致，详情参考授权章节。

仅进行 3DS 认证

EVO Payment 支持您仅通过 EVO Payment 进行 3DS 认证获取 3DS 认证结果而不发起授权。

主要流程如下：

1. 您需要在一笔普通的授权请求（ POST Payment ）中请求中额外添加以下参数：

   • authentication.authenticationOnly：固定值 true。
   • authentication.authenticationMethod：固定值 CILAuth。
   • authentication：包含 3DS 认证相关信息的结构体，详情参考 3DS 章节。

2. 检查 EVO Payment 的应答，如果应答中存在 result.action 字段，则表示该笔交易需要继续进行 3DS 认证（请参考 3DS 章节）。

   如果应答中不存在 result.action 字段，则需要根据 payment.status 字段内容判断 3DS 认证是否结束。如果字段的值为 Verified 则表示 3DS 验证结束，同时您可以从应答中的 authentication.threeDS.mpiData 结构体中找到 3DS 认证结果信息，否则就需要查看 result.code 以及 result.message 来查看交易失败原因。

   下面 3DS 结果列表，展示了 3DS 认证完成后有关 3DS 结果的详细信息：

Card Scheme	ECI	Authentication status	Description
Mastercard	02	Y	3DS 认证通过
	01	A	已尝试认证。没有通过身份认证，但提供了尝试身份认证的证明。
	00	N / U / R / C	N：未认证/帐户认证失败。交易应当被拒绝。 U：无法进行身份认证/帐户认证。技术或其他问题导致。 R：身份认证/帐户认证被拒绝。 发卡行拒绝身份认证，交易应当被拒绝。 C：需要挑战。如果您在上送 CRes 后收到此状态，则表示身份认证被拒绝。
Visa, JCB, AMEX, Diners/Discover, UPI	05	Y	3DS 认证通过
	06	A	已尝试认证。没有通过身份认证，但提供了尝试身份认证的证明。
	07	N / U / R / C	N：未认证/帐户认证失败。交易应当被拒绝。 U：无法进行身份认证/帐户认证。技术或其他问题导致。 R：身份认证/帐户认证被拒绝。 发卡行拒绝身份认证，交易应当被拒绝。 C：需要挑战。如果您在上送 CRes 后收到此状态，则表示身份认证被拒绝。

3. 如果您没有收到来自 EVO Payment 的应答报文，则需要您调用 GET Payment 来查询 3DS 认证是否结束。当收到查询应答时，您同样也需要通过 payment.status 字段内容来判断 3DS 认证是否结束，判断方式与第 2 步一致。如果 3DS 认证终止，您需要通过 payment.failureCode 以及 payment.failureReason 来查看 3DS 认证终止原因。

4. 如果您在 POST Payment 请求中上送了 webhook 并且交易的 payment.status 为 Verified，您也可以通过异步通知来获取 3DS 认证结果，异步通知中的 eventCode 为 Payment。同样也需要通过 payment.status 字段内容来判断 3DS 认证是否结束，判断方式与第 2 步一致。