PayZuDocs

3-D Secure (3DS)

查看 Markdown
PortuguêsEnglish中文

由发卡行完成的持卡人认证,并转移拒付责任。

POST创建收款3DS 测试卡反欺诈

3DS 由发卡行确认付款人确实是持卡人。经过认证的交易可以降低欺诈风险，并且在认证成功时将拒付责任转移给发卡行或卡组织。

在 3DS 认证过程中,买家的信息会共享给卡组织和发卡行,由它们评估交易风险,并决定是否需要挑战验证(例如短信验证码或在银行 App 内认证)来验证持卡人的身份。

优势

  • 降低欺诈
  • 通过认证的交易享有责任转移 (liability shift):发生拒付时由发卡行或卡组织承担责任
  • 通过 JavaScript 即可轻松集成
  • 支持无摩擦认证(买家看不到任何挑战验证),适用于交易风险被判定为低的场景

认证流程

当交易使用 success 事件返回的变量完成授权时,责任 (liability) 转移给发卡行。在其他所有场景中,责任仍由商户承担。

分步集成

初始化脚本

在您的网页中引入以下脚本,它负责与卡组织和发卡行进行通信:

<script src="https://static.payzu.io/scripts/3ds20.min.js"></script>

脚本加载完成后,需要按如下方式初始化:

const config = {
  amount: 350,
  currency: 'BRL',
  options: {
    enabled: true,
    sandbox: true,
    debug: true,
    suppressChallenge: false
  }
};

payzu3DS.init(config);
参数描述类型
amount交易总金额,单位为分整数
currency货币代码固定为 "BRL"
options.enabled定义该交易是否提交到 3DS 认证流程boolean
options.sandbox定义运行环境为 sandbox 还是生产环境boolean
options.debug启用后,日志和报告将输出到浏览器控制台boolean
options.suppressChallenge决定是否跳过挑战验证。如果跳过挑战验证且交易被授权,责任 (liability) 仍由商户承担boolean

注册认证事件

注册事件监听器,以处理认证的每一种可能结果:

payzu3DS.on("ready", function (e) {

});

ready

当脚本的所有加载步骤成功完成(包括访问 token 的校验)时触发此事件,表示 checkout 已就绪,可以开始认证流程。

认证结果

仅当认证成功完成时才发生 liability shift:此时拒付责任转移给发卡行或卡组织。在其他所有场景中,责任仍由商户承担。

事件场景与返回责任 (liability)建议操作
success卡片符合认证条件且认证成功完成。返回 Cavv、Xid 和 Eci。转移给发卡行将 Cavv、Xid 和 Eci 包含在授权请求中。
failure卡片符合认证条件,但认证失败。仅返回 Eci。仍由商户承担如果决定继续授权,在请求中包含 Eci。
unenrolled卡片不符合认证条件:持卡人和/或发卡行未参与 3DS 计划。仅返回 Eci。仍由商户承担提示买家向发卡行确认该卡是否已开通电商认证。
disabled商户选择不认证,将 options.enabled 设为 false。仍由商户承担-
error认证流程发生系统性错误。仍由商户承担-

unsupportedBrand

当所用卡片的卡组织不支持 3DS 协议时触发此事件。此时不会进行认证。

返回的属性

属性描述类型是否必填
Cavv代表认证签名的数据string是
Xid认证交易的标识符string否
Eci代表认证结果的代码ECI 表是
Version所使用的 3DS 协议版本string是
ReferenceId认证请求的标识符string是
ReturnCode认证的返回码3DS 返回码是
ReturnMessage认证的返回消息3DS 返回码是

发起挑战验证

实例化 paymentObject 对象,注意下表中明确标为必填的字段。执行 checkout 时,认证流程随即启动,其结果将通过事件返回。

const paymentObject = {
  installments: '01',
  cardnumber: '4000000000001091',
  cardexpirationmonth: '01',
  cardexpirationyear: '2027',
  cardalias: 'JOAO SOUZA',
  paymentmethod: 'Credit'
}

payzu3DS.checkout(paymentObject)

如果认证成功完成,将触发 success 事件。此时会返回 Cavv、Xid 和 Eci 变量:应将它们发送到您的后端,并在授权时包含在请求中。在这种情况下,liability shift 转移给发卡行。

在收款中使用认证结果

要使用 3DS 创建收款,需要将 authenticate 字段设为 true,并在 creditCardPayment 中提供 externalAuthentication 字段:

{
  "creditCardPayment": {
    "authenticate": true,
    "externalAuthentication": {
      "cavv": "Ag5zZ2ElCIUbLFj6gS0J9gByv//rRg5qGTqWqf8vTjt5",
      "xid": "198b924ea7db1014b64c8b426a0e6f1e",
      "eci": "05",
      "version": "2.2",
      "referenceId": "abcd1234-efgh-5678-ijkl-9012mnopqrst"
    }
  }
}

请求的其余字段请参阅创建收款。

返回码与 ECI

3DS 返回码

3DS 认证流程返回的代码。

3DS 代码描述建议操作
100交易成功完成。-
101请求缺少一个或多个必填字段。检查响应中的 missingField_0 至 missingField_N 字段,然后重新发送请求。
102请求中一个或多个字段包含无效数据。检查响应中的 invalidField_0 至 invalidField_N 字段,然后重新发送请求。
150错误:系统整体故障。请等待几分钟后重新发送请求。
151错误:请求已被接收,但服务器发生超时。请等待几分钟后重新发送请求。
152错误:请求已被接收,但服务发生超时。请等待几分钟后重新发送请求。
234您的 merchant 配置存在问题。请勿重新发送该请求,请联系支持团队。
475该客户已注册付款人认证。在继续交易前,请先完成持卡人认证。
476无法对该客户进行认证。请复核该客户的订单。
MPI901意外错误。-
MPI902认证返回了意外响应。-
MPI900发生了一个错误。-
MPI601认证挑战已被省略。-
MPI600卡组织不支持该认证。-

ECI 表

ECI 表按卡组织显示认证结果,以及由谁承担拒付(chargeback)风险:

MastercardVisaEloAmex认证结果交易是否已认证?
02050505由发卡行认证:拒付风险转由发卡行承担。是
01060606由卡组织认证:拒付风险转由发卡行承担。是
非 01、02 和 04非 05 和 06非 05 和 06非 05 和 06未认证:拒付风险仍由商户承担。否
047--未认证,交易被标记为 Data Only:拒付风险仍由商户承担。否

当交易未通过认证时,拒付风险仍由商户承担。在决定是否继续该笔收款之前,请先核对上表中的 ECI 值。

参考

  • 在 sandbox 中模拟各种 3DS 认证场景的卡片:测试卡
测试卡反欺诈

本页内容

优势认证流程分步集成初始化脚本注册认证事件ready认证结果unsupportedBrand返回的属性发起挑战验证在收款中使用认证结果返回码与 ECI3DS 返回码ECI 表参考