身份验证常见问题
3D 验证常见问题
您可以在 Merchant Administration 门户中查看为继续处理付款所进行的各个身份验证和身份验证的身份验证详细信息。 请在搜索页面搜索订单或交易，然后查看身份验证详细信息。
例如，如果您要查看 3DS1 身份验证的身份验证详细信息，例如，要查看 PARes、PAReq 等字段的数据，请使用 Merchant Administration 门户中的身份验证搜索选项。
如果您使用身份验证 API，付款人身份验证完成后，您可以在 Merchant Administration 门户上查看身份验证详细信息。 如果付款人身份验证尚未完成，您在 Merchant Administration 门户上搜索订单或交易时显示的身份验证交易可能会出现延迟。 例如，经过质询流。
同时，您可以使用 Retrieve Order 或 Retrieve Transaction 操作来检索身份验证的当前状态。
如果您希望在任何阶段检索身份验证结果，请使用 Retrieve Transaction 操作。 请注意，仅在身份验证期间使用的字段（例如，authentication.redirect.html）不会在网关中保留，因此不会返回。
如果您已使用外部 3DS MPI 对付款人进行身份验证，那么您必须将有关身份验证的信息传入 Authorize 或 Pay 操作的身份验证参数组中。
所有字段均为可选字段，因为是否由外部 3DS MPI 向您提供这些字段取决于交易的身份验证版本（3DS1 或 3DS2）和状态。 不过，如果您有数据，建议您提供数据。
authentication.3ds.acsEci: 可能在身份验证响应消息中返回给您的电子商务指示符。authentication.3ds.authenticationToken: 发卡机构生成的可能在身份验证响应消息中返回给您的 base64 编码值。authentication.3ds.transactionId: 网关为 3DS 身份验证生成的唯一交易识别码。
对于 3DS1，此字段与 XID 对应，是网关代表商家生成的标识符。 在此字段中提交的 XID 必须是 base64 格式。
对于 3DS2，此字段对应于组织 Directory Server 分配的标识符。authentication.3ds2.protocolVersion: 用于执行 3DS 支付验证的 EMV 3D 安全协议的版本，使用 EMVCo 指定的格式。 例如，2.1.0authentication.3ds2.transactionStatus: 指示发卡机构执行的付款人身份验证结果。authentication.3ds2.statusReasonCode: 指示authentication.3ds2.transactionStatus中返回的交易状态原因的代码。 当authentication.3ds2.transactionStatus返回 N、U 或 R 时，必须提供此字段。authentication.amount: 这是一个可选字段。 指示身份验证金额。 您需要在身份验证金额与order.amount不同时，在此字段中提供值。 请在此字段中提供值之前，先与您的支付服务提供商进行确认。authentication.time: 这是一个可选字段。 指示付款人进行身份验证的日期和时间。 请在此字段中提供值之前，先与您的支付服务提供商进行确认。
authentication.3ds.authenticationToken。如果您是一家在沙特阿拉伯王国设置了 mada 收单行链接的电子商务商家，有在网关外完成完全 3DS 身份验证的付款人，您必须集成到 WS API 版本 76 或更高版本，并在 Authorize 或 Pay 操作中提供以下身份验证详细信息，才能成功提交 mada 联名卡、mada 单标卡或国际卡交易：
authentication.3ds2.acsReference: 指定 EMVCo 在 ACS 批准后分配给发卡机构的访问控制服务器 (ACS) 的参考号。 此字段对应于 EMVCo 字段 acsReferenceNumber。authentication.3ds2.dsReference: 指定 EMVCo 在 DS 批准后分配给 Directory Server (DS) 的参考号。 此字段对应于 EMVCo 字段 dsReferenceNumber。authentication.3ds2.acsTransactionId: 指定访问控制服务器分配用于标识 3DS 交易的唯一交易标识符。authentication.time: 指定付款人进行身份验证的日期和时间。 此字段对应于 EMVCo 字段 purchaseDate。authentication.3ds.acsEci: 指定发卡机构的访问控制服务器 (ACS) 提供的电子商务指示符 (ECI) 值，用于指示尝试对付款人执行身份验证的结果。authentication.3ds.authenticationToken: 指定发卡机构生成的 base64 编码值。 此字段对应身份验证值。authentication.3ds.transactionId: 对应于 DS 交易 ID。authentication.3ds2.protocolVersion: 指定用于执行 3DS 支付验证的 EMV 3D 安全协议的版本。 例如，2.1.0。authentication.3ds2.transactionStatus: 对应于 EMVCo 字段 transStatus。authentication.3ds2.authenticationScheme: 对于在外部完成身份验证的 mada 联名交易，您必须提供 MADA、MASTERCARD 或 VISA 来指定用于为交易执行身份验证的 3DS Directory Server。 对于在外部完成身份验证的 mada 单标交易，您可以提供 MADA 或不提交此字段。 对于其他卡，您可以提供相应的身份验证方案或不提交此字段。
如果您执行身份验证只是为了验证付款人的身份，而不继续处理付款，您必须在 Initiate Authentication 请求中指明身份验证的目的。 例如，付款人输入他的卡详细信息以供以后在您的网站上进行客户注册或创建账户时使用，这时，您可能希望对付款人执行身份验证。 能够在非付款环境中完成身份验证过程可以增强付款人体验，降低付款人的放弃比率。
要执行非支付身份验证，在 Initiate Authentication 请求中提供以下字段：
- order.currency： 收单行链接上支持的任何货币。
- authentication.purpose： 指示正在请求付款人身份验证的上下文。 您可以指定以下其中一项：
- ADD_CARD： 在将付款人的卡存档之前直接由您或使用网关的令牌化功能执行的身份验证。 付款未被处理。
- MAINTAIN_CARD： 在更新已存档的付款人的卡详细信息之前，直接由您或使用网关的令牌化功能执行的身份验证。 付款未被处理。
如果身份验证方案不支持您请求的目的，网关将在响应中返回
AUTHENTICATION_NOT_SUPPORTED。 请注意，默认情况下，网关会将此字段设置为PAYMENT_TRANSACTION，以允许将身份验证用于付款交易。
整合方商家可以支持他们的下级商家在网关上使用身份验证 API。 下级商家不需要与收单行或网关之间有合同关系。 整合方商家可以通过 Initiate Authentication 操作提交发起身份验证所需的下级商家详细信息。 有关详细信息，请参见整合方支持。
身份验证 API 在订单上将使用 3DS2 的付款人身份验证的详细信息记录为单独的 AUTHENTICATION 交易。
当您使用 Retrieve Order 操作检索订单或收到 Reporting API 响应时，它可能包含额外的 AUTHENTICATION 交易。 此外，当您使用 Webhook 通知时，也可能会收到额外的 AUTHENTICATION 交易通知。
有关 AUTHENTICATION 交易的详细信息，请参阅 Authenticate Payer 操作的响应参数列表。
从 DirectAPI v57 开始，您可以将网络令牌用于付款人身份验证。 Mastercard Gateway 目前支持处理从以下令牌化服务提供商获取的网络令牌： Mastercard Digital Enablement Service (MDES)、Visa Token Service (VTS)。
如果您是通过直接集成到网络令牌化服务提供商获得的网络令牌，则必须使用以下字段提供令牌详细信息：
sourceOfFunds.type=SCHEME_TOKEN: 让网关能够识别在请求中作为网络令牌提供的资金来源。 DirectAPI v51 和 v53 分别支持 MDES 和 VTS。sourceOfFunds.provided.card.number: 网络令牌。 为 MDES“令牌 PAN”或 VTS“令牌”提供值。sourceOfFunds.provided.card.expiry: （可选）网络令牌过期。
如果您的支付服务提供商已为您启用了网络令牌化，在发卡机构支持的情况下，任何向网关请求网关令牌的请求还会尝试为启用的方案生成相应的网络令牌。 网关还将尝试对已经存储在网关令牌库中的所有适用卡进行网络令牌化。 Initiate Authentication 请求将使用网络令牌（如果可用），否则将使用通过网关令牌存储的资金提供 PAN (FPAN)。 此模式目前仅支持 MDES 令牌。
如果您使用付款会话（会话 ID）来存储身份验证详细信息，在 Authenticate Payer 请求完成后付款人的浏览器向您的网站提交的 POST 请求将以参数表示，以便确定身份验证结果。 单独的身份验证参数（例如，authentication.3ds2.transactionStatus.data）在高级集成中，或需要在通过另一个网关处理的付款中提供身份验证数据时可能很有用。 要实现此目的，您可以提交 Retrieve Transaction 请求或选择解密加密的身份验证数据（请参见以下步骤）：
- 使用 Create Session 操作创建会话。
- 使用 Update Session 请求将相关数据添加到会话 ID（在 Create Session 响应中返回）中。
- 在 Initiate Authentication 和 Authenticate Payer 请求中使用此会话 ID。
- 付款人浏览器到您的网站的重定向将在
encryptedData字段中包含付款人身份验证详细信息。 它是一个加密的 JSON 对象，包含在身份验证流程中获取的身份验证数据。 它包含以下字段：encryptedData.ciphertextauthentication.3ds.acsEciauthentication.3ds.authenticationTokenauthentication.3ds.transactionIdauthentication.3ds1.veResEnrolledauthentication.3ds1.paResStatusauthentication.3ds2.transactionStatusauthentication.3ds2.dsTransactionIdtransaction.authenticationStatusauthentication.3ds2.statusReasonCodesourceOfFunds.provided.card.numbersourceOfFunds.provided.card.expiry.monthsourceOfFunds.provided.card.expiry.yearsourceOfFunds.tokenorder.idtransaction.idencryptedData.nonceencryptedData.tag
- 要解密 encryptedData.ciphertext 字段中返回的内容，请在 GCM 模式下使用 session.aes256Key（在 Create Session 响应中返回）。 Base64 编码密钥为机密信息，您只能自己知道。
public final class SessionDataDecrypter {
/**
* The algorithm used for encryption/decryption
*/
private static final String SYMMETRIC_ALGORITHM = "AES/GCM/NoPadding";
/**
* The algorithm to be associated with the secret key material
*/
private static final String SYMMETRIC_KEY_TYPE = "AES";
/**
* The secret key associated with the session, as returned in the session.aes256Key in a Create Session response.
*/
private final byte[] key;
/**
* Constructs a new object with the given key. The key is Base64 encoded, as returned in the session.aes256Key
* field in a Create Session response. This key must be kept secret, as it may be used to encrypt, decrypt and
* authenticate data for that session.
*
* @param encodedKey Key to be used for decryption.
*/
public SessionDataDecrypter(String encodedKey) {
key = Base64.getDecoder().decode(encodedKey);
}
/**
* Performs decryption of the given ciphertext, using the key passed in the constructor and the associated nonce.
* The tag is used to authenticate the ciphertext.
*
* @param ciphertext Encrypted and authenticated session data
* @param nonce Nonce/Initialization vector associated with the ciphertext
* @param tag Authentication tag
* @return The decrypted session data
* @throws AEADBadTagException if the data cannot be authenticated with the given tag
* @throws InvalidKeyException if the key cannot be constructed properly. This may indicate that it has not been
* correctly retrieved from the response field
* @throws GeneralSecurityException other than {@link AEADBadTagException} and {@link InvalidKeyException}, should
* not be thrown in a correctly set up environment
*/
public String decrypt(String ciphertext, String nonce, String tag)
throws GeneralSecurityException {
Key keySpec = new SecretKeySpec(key, SYMMETRIC_KEY_TYPE);
// The Java crypto classes expect the ciphertext and tag to be a single input, so they need to be concatenated
byte[] encryptedBytes = Base64.getDecoder().decode(ciphertext);
byte[] tagBytes = Base64.getDecoder().decode(tag);
byte[] input = new byte[encryptedBytes.length + tagBytes.length];
System.arraycopy(encryptedBytes, 0, input, 0, encryptedBytes.length);
System.arraycopy(tagBytes, 0, input, encryptedBytes.length, tagBytes.length);
// Configure the cipher with AES, using GCM parameter specifying the nonce/initialization vector
byte[] iv = Base64.getDecoder().decode(nonce);
GCMParameterSpec parameterSpec = new GCMParameterSpec(tagBytes.length * Byte.SIZE, iv);
final Cipher decrypter = Cipher.getInstance(SYMMETRIC_ALGORITHM);
decrypter.init(Cipher.DECRYPT_MODE, keySpec, parameterSpec);
// Perform the decryption and return the value.
byte[] decryptedBytes = decrypter.doFinal(input);
return new String(decryptedBytes, StandardCharsets.UTF_8);
}
}
Authenticate Payer 请求可以获取大量有关付款人和交易的信息。 例如，您可以使用 customer.account 参数组中的字段在请求中提供以下数据，这可以帮助发卡机构的 ACS 评估与活动相关的风险级别。 这意味着在合法付款的情况下，可以帮助 ACS 确认付款人有可能是实际的持卡人。
- 付款人使用的是否是现有账户？
customer.account.history.creationDate
- 此账户存在了多长时间？
customer.account.history.lastUpdatedcustomer.account.history.passwordLastChanged
- 付款人在您这里多久购物一次？
customer.account.history.addCardAttemptscustomer.account.history.annualActivitycustomer.account.history.recentActivitycustomer.account.history.shippingAddressDate
- 他们以前是否在您这里订购过这些物品？
customer.account.history.issuerAuthentication.acsTransactionIdcustomer.account.history.issuerAuthentication.timecustomer.account.history.issuerAuthentication.type
- 您是否发现此账户有可疑活动（例如，登录尝试失败）？
customer.account.history.suspiciousActivitycustomer.account.authentication.methodcustomer.account.authentication.time
您还可以在 Authenticate Payer 请求中为每个卡组织提供以下建议字段。 请注意，此列表不是最后版本，可能会有变化。
| 字段 | Mastercard | Visa | American Express | 注释 |
|---|---|---|---|---|
| shipping.contact.email | - | - | Y | 计算商家风险时需要 |
| shipping.method | - | - | Y | 计算商家风险时需要 |
| order.valueTransfer.amount | - | - | Y | 计算商家风险时需要。 仅适用于礼品卡。 |
| order.valueTransfer.numberOfCards | - | - | Y | 计算商家风险时需要。 仅适用于礼品卡。 |
| order.valueTransfer.currency | - | - | Y | 计算商家风险时需要。 仅适用于礼品卡。 |
| order.supply.preorderAvailabilityDate | - | - | Y | 计算商家风险时需要 |
| order.supply.preorder | - | - | Y | 计算商家风险时需要 |
| order.supply.reorder | - | - | Y | 计算商家风险时需要 |
| order.valueTransfer.accountType | - | Y | - | Visa 和某些市场（例如，巴西）的其他计划需要。 order.valueTransfer.accountType=NOT_A_TRANSFER 时不适用 |
网关在 transaction.authenticationStatus 字段中提供身份验证状态。 根据身份验证阶段，此字段可能会返回以下值之一：
AUTHENTICATION_ATTEMPTED: 尝试了付款人身份验证，并获得了身份验证尝试证明。AUTHENTICATION_AVAILABLE: 所提供的付款方式可以使用付款人身份验证。AUTHENTICATION_FAILED: 未对付款人进行身份验证。 您不应该继续处理此交易。AUTHENTICATION_NOT_SUPPORTED: 此付款方式不支持请求的身份验证方法。AUTHENTICATION_NOT_IN_EFFECT: 没有与此交易关联的身份验证信息。AUTHENTICATION_PENDING: 付款人身份验证正在等待质询流程完成。AUTHENTICATION_REJECTED: 发卡机构拒绝了身份验证请求，并要求您不要尝试付款授权。AUTHENTICATION_REQUIRED: 此付款需要进行付款人身份验证，但未提供。AUTHENTICATION_SUCCESSFUL: 付款人成功通过身份验证。AUTHENTICATION_UNAVAILABLE: 由于技术或其他问题，付款人无法进行身份验证。
支付身份验证数据的有效时长可能取决于您的用例。 如果您需要说明，请联系 your payment service provider。
要将重复交易与身份验证一起使用，请参见存档凭据、持卡人发起交易和商家发起交易。
从 DirectAPI v55 开始，您可以将设备付款令牌用于付款人身份验证。 仅支持从 Google Pay SDK 获取的付款令牌。 您可以提供加密付款令牌或从已解密付款令牌获取的“pan”来进行付款人身份验证。 网关仅接受带有 FPAN 的身份验证请求，带有 DPAN 的请求将被拒绝。 要通过付款令牌提供卡详细信息，请提供以下字段：
order.walletProvider=GOOGLE_PAYsourceOfFunds.provided.card.devicePayment.paymentToken: 仅在付款令牌由网关解密时适用。 它是从 Google Pay SDK 获取的加密付款令牌。sourceOfFunds.provided.card.number: 仅在付款令牌由您解密时适用。 与 Google Pay JSON 密钥“pan”对应的值。
在发起付款人身份验证之前，您可以通过提交 Payment Options Inquiry 请求来获取 DCC 提供商的动态货币兑换 (DCC) 费率报价。
如果 DCC 提供商已出价，您已将此出价提供给付款人，并且付款人已接受该出价，则您必须在 Initiate Authentication 请求中包含以下内容：
- 在 Payment Options Inquiry 响应中返回的 currencyConversion.requestId
- currencyConversion.uptake=ACCEPTED
如果付款人拒绝了出价，请在 Initiate Authentication 请求中指示：
- 在 Payment Options Inquiry 响应中返回的 currencyConversion.requestId
- currencyConversion.uptake=DECLINED
如果此交易不需要 DCC，请提交 Initiate Authentication 请求并指示：
- currencyConversion.uptake=NOT_REQUIRED
如果您配置为使用 DCC，并且未在 Initiate Authentication 请求中提供 currencyConversion.uptake，Initiate Authentication 响应会指示 currencyConversion.uptake=NOT_REQUIRED。
如果付款人接受 DCC 出价，付款人身份验证过程将使用付款人的货币和付款人的金额。 在所有其他情况下，付款人身份验证过程使用订单金额和订单货币。
您可以通过引用身份验证交易（即 authentication.transactionId）在后续的付款请求中使用 Initiate Authentication 请求中提供的 DCC 信息。 付款人身份验证期间提交的 DCC 信息将应用于您的付款交易。
您还可以选择提交相同的 DCC 信息进行身份验证以及后续付款交易。
如果引用身份验证交易的后续付款交易包含不同的 DCC 信息，付款交易将被拒绝。
- 付款人身份验证，导致回退到 3DS1
- 商家发起的身份验证，包括刷新付款人身份验证。