身份验证

POST 您的身份验证请求到 3ds:authenticate 操作链接。您的身份验证请求会发送用于决定是否需要质疑的订单和风险数据。

身份验证示例请求

POST https://try.access.worldpay.com/verifications/customers/3ds/authentication

身份验证请求正文：

Copied!

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
      "entity": "MindPalaceLtd",
      "overrideName": "The Baskerville Animal Sanctuary"
  },
  "instruction": {
    "paymentInstrument": {
      "type": "card/front",
      "cardHolderName": "Sherlock Holmes",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 5,
        "year": 2035
      },
      "billingAddress": {
          "address1": "221B Baker Street",
          "address2": "Marylebone",
          "address3": "Westminster",
          "postalCode": "NW1 6XE",
          "city": "London",
          "countryCode": "GB"
      }
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    }
  },
  "deviceData": {
    "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5",
    "acceptHeader": "text/html",
    "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)",
    "browserLanguage": "en-GB",
    "ipAddress": "192.0.0.0"
  },
  "challenge": {
    "windowSize": "600x400",
    "preference": "noPreference",
    "returnUrl": "http://payment.example.com"
  },
  "riskData": {
    "account": {
      "previousSuspiciousActivity": false,
      "type": "registeredUser",
      "email": "sherlock.holmes@example.com",
      "history": {
        "createdAt": "2019-11-18",
        "modifiedAt": "2019-11-18",
        "passwordModifiedAt": "2019-10-15",
        "paymentAccountEnrolledAt": "2019-11-18"
      }
    },
    "transaction": {
      "reorder": true,
      "preOrderDate": "2019-11-18",
      "firstName": "Sherlock",
      "lastName": "Holmes",
      "phoneNumber": "00000000000",
      "history": {
        "attemptsLastDay": 2,
        "attemptsLastYear": 6,
        "completedLastSixMonths": 6,
        "addCardsLastDay": 5,
        "shippingAddressFirstUsedAt": "2018-09-18"
      },
      "giftCardsPurchase": {
        "totalValue": {
          "currency": "GBP",
          "amount": 10
        },
        "quantity": 4
      }
    },
    "shipping": {
      "nameMatchesAccountName": false,
      "method": "verifiedAddress",
      "timeFrame": "nextDay",
      "email": "sherlock.holmes@example.com",
      "address": {
        "address1": "Disneyland",
        "address2": "Disneyland Drive",
        "address3": "Adventure Park",
        "postalCode": "DL1 2CA",
        "city": "Anaheim",
        "stateCode": "CA",
        "countryCode": "GB",
        "phoneNumber": "01911234321"
      }
    }
  }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd",
        "overrideName": "The Baskerville Animal Sanctuary"
    },
    "instruction": {
        "paymentInstrument": {
            "type": "card/tokenized",
            "href": "https://try.access.worldpay.com/tokens/MTIzNDU2Nzg5MDEyMzQ1Ng"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        }
    },
    "deviceData": {
        "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5",
        "acceptHeader": "text/html",
        "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)",
        "browserLanguage": "en-GB",
        "ipAddress": "192.0.0.0"
    },
    "challenge": {
        "windowSize": "600x400",
        "preference": "noPreference",
        "returnUrl": "http://payment.example.com"
    },
    "riskData": {
        "account": {
            "previousSuspiciousActivity": false,
            "type": "registeredUser",
            "email": "test@test.com",
            "history": {
                "createdAt": "2019-11-18",
                "modifiedAt": "2019-11-18",
                "passwordModifiedAt": "2019-10-15",
                "paymentAccountEnrolledAt": "2019-11-18"
            }
        },
        "transaction": {
            "reorder": true,
            "preOrderDate": "2019-11-18",
            "firstName": "John",
            "lastName": "Appleseed",
            "phoneNumber": "00000000000",
            "history": {
                "attemptsLastDay": 2,
                "attemptsLastYear": 6,
                "completedLastSixMonths": 6,
                "addCardsLastDay": 5,
                "shippingAddressFirstUsedAt": "2018-09-18"
            },
            "giftCardsPurchase": {
                "totalValue": {
                    "currency": "GBP",
                    "amount": 10
                },
                "quantity": 4
            }
        },
        "shipping": {
            "nameMatchesAccountName": false,
            "method": "verifiedAddress",
            "timeFrame": "nextDay",
            "email": "sherlock.holmes@example.com",
            "address": {
                "address1": "Disneyland",
                "address2": "Disneyland Drive",
                "address3": "Adventure Park",
                "postalCode": "DL1 2CA",
                "city": "Anaheim",
                "stateCode": "CA",
                "countryCode": "GB",
                "phoneNumber": "01911234321"
            }
        }
    }
}

需提供的数据数量

发卡机构使用authentication请求中的设备数据和值来确定交易是否可能为欺诈。这些数据的解释方式因发卡机构而异，但提供更多数据将增加无障碍达成结果（无挑战）的可能性，并且对于某些发卡机构而言，身份验证完全失效。

我们建议的可选数据至少包括：

paymentInstrument.billingAddress - 含子值
deviceData.collectionReference
riskData.account.email
riskData.transaction.firstName
riskData.transaction.lastName
riskData.transaction.phoneNumber

详情请参见下表，其中清楚地标记为 recommended。

参数描述

有关 API 架构，请参见API 参考。

参数	必需	描述
`transactionReference`		独特的身份验证参考号。例如，电子商务订单代码。在所有 3 个潜在请求类型（deviceDataInitialization、authentication、verification）中使用相同的 `transactionReference`。
`merchant.entity`		作为加入流程的一部分而创建，用于在 Access Worldpay 中发送身份验证请求。
`instruction`		包含与身份验证请求相关的所有支付信息的对象。
`instruction.paymentInstrument`		包含银行卡资料或 Token 位置的对象。
`paymentInstrument.type`		所使用的 `paymentInstrument` 的识别码。 `type`: `card/front` 请参见上文身份验证（卡） `type`： `card/tokenized` 请参见上文身份验证 (token)
`paymentInstrument.billingAddress`	Recommended	包含账单邮寄地址信息的对象。如果已包括，则您必须至少要发送： `address1` `city` `countryCode` `postalCode` `state`- 只应按照 ISO-3611-2 二字符细分规范来提供，e.g.，“CA”表示加利福尼亚州。我们建议您在美国地址中提供此信息
`instruction.value`		包含有关身份验证值信息的对象。
`value.currency`		三位数货币代码。请参见支持的货币列表。
`value.amount`		身份验证金额。这是一个包含小数位的整数，e.g.，如果小数位是二，则 250 就表示 2.50.您可以在我们的货币表中查找相关小数位。身份验证金额应等于授权金额。我们建议您在知道金额之后再进行身份验证，或者确保其大于总交易金额。
`deviceData.acceptHeader`		由发卡机构用于核实客户的浏览器是否与发卡机构质疑显示兼容。
`deviceData.userAgentHeader`		由发卡机构用于风险分析的一部分并正确显示质疑。必须符合RFC 7321 E.g. `Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)`
`deviceData.collectionReference`	Recommended	对于 Web，这是设备数据收集表中 postMessage 响应中的 `session Id` 对于 iOS/Android SDK，这是作为SDK 和设备数据初始化一部分返回的 `consumerSessionId` 注释：如果未提供值，则身份验证会回退至 3DS1。
`challenge.windowSize`		指定发卡机构应使用的质疑窗口大小（宽 x 高）。这样可以更好地根据客户设备来定制体验。 `250x400` `390x400`（默认值） `600x400` `500x600` `fullpage` - 展开以填满视区注释：3DS1 规范默认值为 390x400，但我们建议最小使用 400x500，因为并非所有发行机构都会严格遵守此规定
`challenge.preference`		`noPreference` - 默认值 `noChallengeRequested` - 首选不执行质疑 `challengeRequested` - 首选执行质疑 `challengeMandated` - 本地或区域规定要求必须执行质疑重要提示：您应在身份验证请求中使用 `challengeMandated`，作为 MIT 系列中第一笔 CIT 支付的一部分。我们强烈建议在一般情况下首次存储卡片时设置此选项（e.g. 首次支付时存储代币或将卡片单独"添加到"账户）。各发卡机构对于此字段的理解各异，因此 Worldpay 无法保证由于您设置了该字段而导致其产生任何特定行为。
`challenge.returnUrl`		一旦客户填写了质疑页面，发卡机构就会重定向/发布至 `returnUrl`，以便您恢复会话。它必须是完整的 URL 路径。

风险数据

为了减少出现 challenged 结果的机会，我们建议您将其他 riskData 纳入您的身份验证请求中。

共有三个 riskData 对象可供您纳入请求中：

账户

参数	必需	描述
`account`		包含所有客户账户相关风险数据的对象。
`account.previousSuspiciousActivity`		true false
`account.type`		`guestUser` - 未经过完整商户账户注册而下达的订单（无密码） `registeredUser`- 已经过完整商户账户注册而下达的订单（输入了密码） `federatedAccount` - 使用联合 ID `issuerCredentials`- 使用发卡机构凭证 `thirdPartyAuthentication` - 使用第三方身份验证 `fidoAuthenticator` - FIDO 身份验证标准
`account.email`	Recommended	客户的电邮地址。
`account.history.createdAt`		在创建账户时。
`account.history.modifiedAt`		在上次修改账户时。
`account.history.passwordModifiedAt`		在上次更改账户密码时。
`account.history.paymentAccountEnrolledAt`		支付账户被添加到持卡人账户的日期。

交易

参数	必需	描述
`transaction`		包含所有客户交易相关风险数据的对象。
`transaction.reorder`		重复上一个订单： true false
`transaction.preOrderDate`		可以预先订购的预期日期。
`transaction.firstName`	Recommended	客户的名字。
`transaction.lastName`	Recommended	客户的姓氏。
`transaction.phoneNumber`	Recommended	客户的电话号码。
`transaction.history`		包含上次交易详情的对象。
`history.attemptsLastDay`		过去 24 小时内该持卡人账户的交易次数（成功或放弃）。
`history.attemptsLastYear`		过去一年内该持卡人账户的交易次数（成功或放弃）。
`history.completedLastSixMonths`		过去六个月内该客户账户的购买次数。
`history.addCardsLastDay`		过去 24 小时内尝试添加卡的次数。
`history.shippingAddressFirstUsedAt`		用于该交易的收货地址首次使用的时间。
`transaction.giftCardsPurchase`		该订单是否被用于购买礼品卡。
`giftCardsPurchase.totalValue.currency`		三位数货币代码。请参见支持的货币列表。如果提供，则必须包括 `totalValue.amount`。
`giftCardsPurchase.totalValue.amount`		礼品卡中充入的金额。如果提供，则必须包括 `totalValue.currency`。
`giftCardsPurchase.quantity`		购买的礼品卡数量。

运输

参数	必需	描述
`shipping`		包含与订单发货方式相关的所有数据的对象。
`shipping.nameMatchesAccountName`		账户中的客户姓名与收货姓名完全相同： true false
`shipping.method`		`billingAddress` - 发货至客户账单邮寄地址 `verifiedAddress`- 发货至商户已验证的另一个地址 `otherAddress`- 发货至不同于账单邮寄地址的地址 `store` - 发货至商店（商店地址应填写在请求中） `digital` - 数字货物 `unshippedTickets` - 旅行和活动门票，未发货 `other` - 其他
`shipping.timeFrame`		`electronic` `sameDay` `nextDay` `twoDaysPlus`
`shipping.email`		用于电子交付的电邮地址。

身份验证响应

最佳实践：Access Worldpay 在服务响应的头文件中返回WP-CorrelationId。我们强烈建议您将此记录下来。我们使用WP-CorrelationId检查单个服务请求。

该响应包含您的身份验证请求的结果。

Copied!

{
    "outcome": "authenticated",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0",
        "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}

{
    "outcome": "authenticationFailed",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0",
        "eci": "07",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    },
    "_links": {
        "3ds:authenticate": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/authentication"
        },
        "curies": [{
            "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}

{
    "outcome": "challenged",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0"
    },
    "challenge": {
        "reference": "123456789",
        "url": "https://ChallengePageUrl.example.com",
        "jwt": "VGhpcyBpcyBhIGJhc2UgNjQgZW5jb2RlZCBleGFtcGxlIG9mIGEgM0RTICJwYXlsb2FkIg==",
        "payload": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVE"
    },
    "_links": {
        "3ds:verify": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/verification"
        },
        "curies": [{
            "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}

{
    "outcome": "notEnrolled",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "1.0.2",
        "eci": "06"
    }
}

{
    "outcome": "unavailable",
    "transactionReference": "Memory265-13/08/1876",
    "_links": {
        "3ds:authenticate": {
            "href": "https://try.access.worldpay.com/verifications/customers/3ds/authentication"
        },
        "curies": [{
            "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}",
            "templated": true,
            "name": "3ds"
        }]
    }
}

{
    "outcome": "bypassed",
    "transactionReference": "Memory265-13/08/1876",
    "authentication": {
        "version": "2.1.0",
        "eci": "07",
        "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
}

参数	描述
`outcome`	您身份验证请求的结果。 `authenticated`- 成功的无摩擦身份验证。 `authenticationFailed`- 您客户无法成功通过身份验证。 `challenged`- 不应信任身份验证详情。必须进行质疑。 `notEnrolled`- 发卡机构未注册 3DS。 `unavailable`- 身份验证不可用。 `bypassed`- 3DS 校验被绕过。如果启用了 3DS 高级功能或在连接到 3DS 目录服务器时出现超时，则会返回此信息。要了解有关 `outcomes` 以及如何再现这些信息的更多详情，请参见3DS 测试。
`challenge.reference`	这会将身份验证响应链接到后续质疑表单和验证请求。
`challenge.url`	POST 质疑表中的操作。作为质疑表的一部分用于重定向至发卡机构质疑页面。不要在 iframe 中将 `challengeUrl` 用作来源 (src)。
`challenge.jwt`	包含其他详情（比如在质疑屏幕之后返回的 URL）的数字签名 Token。对于 Try 和 Production 版都将在 10 分钟后到期。
`challenge.payload`	包含质疑所需额外数据的 JSON 容器。注释：这仅适用于本地移动应用程序 SDK。对于 Web 集成它不是必需的。
`authentication.version`	用于处理该交易的 3DS 版本。注释：对于授权中的 Mastercard 身份校验交易是必需的。
`authentication.authenticationValue`	提供 3DS 验证结果证据的密码值。 Visa - 持卡人身份验证的验证值 (CAVV) Mastercard - 通用持卡人身份验证字段 (UCAF) 在授权支付时使用。
`authentication.eci`	电子商务指标 (ECI)。表示 3DS 身份验证的结果。 02 或 05 - 完全身份验证的交易 01 或 06 - 尝试身份验证的交易 00 或 07 - 非 3-D 安全交易 Mastercard - 02、01、00 Visa - 05、06、07 Amex - 05、06、07 JCB - 05、06、07 Diners - 05、06、07 您会在授权支付时用到它。
`authentication.transactionId`	交易识别码。如果提供，则您应将它用作支付授权的一部分。如果 `authentication.version` 具有以下主要版本： `1`- 作为 `xid`返回的值 `2` - 作为 `dsTransactionId` 返回的值

注释：如果出现错误，您可以在我们的错误参考中获取更多信息。

后续步骤

质疑
接受支付
3DS 测试

Translation disclaimer

身份验证

身份验证示例请求

需提供的数据数量

参数描述

风险数据

账户

交易

运输

身份验证响应

Searching accross the entire site

Filter by product

Filter by product Searching across the entire site

Translation disclaimer Collapse

身份验证

身份验证示例请求

需提供的数据数量

参数描述

风险数据

账户

交易

运输

身份验证响应

Searching accross the entire site

Filter by product

Filter by product Searching across the entire site

​

Translation disclaimer