Authentication Frequently Asked Questions
3-D Secure frequently asked questions
You can view authentication details for both individual authentications and authentications that proceeded with the payment in the Merchant Administration portal. Search for the order or transaction in the search page and view the authentication details.
If you want to view authentication details for a 3DS1 authentication, for example, to view data for fields such as PARes, PAReq, then use the Authentications search option in the Merchant Administration portal.
If you use the Authentication API, you can see the authentication details on the Merchant Administrator portal when the payer authentication is complete. If the payer authentication is not yet complete, you may experience a delay in the authentication transaction that displays when searching for an order or transaction on the Merchant Administrator portal. For example, going through a challenge flow.
In the meantime, you can retrieve the current state of the authentication using the Retrieve Order or Retrieve Transaction operation.
If you wish to retrieve the authentication results at any stage, use the Retrieve Transaction operation. Note that fields that are only used during the authentication, for example, authentication.redirect.html, are not persisted in the gateway hence not returned.
If you have used an external 3DS MPI to authenticate the payer, then you must pass information about the authentication in the authentication parameter group of the Authorize or Pay operation.
All fields are optional, as whether or not they were provided to you by the external 3DS MPI depends on the authentication version (3DS1 or 3DS2) and the status of the transaction. However, if you have the data it's recommended that you provide it.
authentication.3ds.acsEci: The Electronic Commerce Indicator that may be returned to you in the authentication response message.authentication.3ds.authenticationToken: The base64 encoded value generated by the card issuer that may be returned to you in the authentication response message.authentication.3ds.transactionId: A unique transaction identifier generated by the gateway for the 3DS authentication.
For 3DS1, this field corresponds to XID, which is an identifier generated by the gateway on behalf of the merchant. An XID submitted in this field must be in base64 format.
For 3DS2, this field corresponds to the identifier assigned by the scheme directory server.authentication.3ds2.protocolVersion: The version of the EMV 3-D Secure protocol used to perform 3-D Secure authentication, in the format specified by EMVCo. For example, 2.2.0authentication.3ds2.transactionStatus: Indicates the result of payer authentication with the issuer.authentication.3ds2.statusReasonCode: A code indicating the reason for the transaction status returned inauthentication.3ds2.transactionStatus. You must provide this whenauthentication.3ds2.transactionStatusreturns N, U, or R.authentication.amount: This is an optional field. It indicates the authentication amount. You need to provide values in this field when the authentication amount differs from theorder.amount. Please check with your payment service provider before providing values in this field.authentication.time: This is an optional field. It indicates the date and time of the payer's authentication. Please check with your payment service provider before providing values in this field.
authentication.3ds.authenticationToken.If you are an e-commerce merchant set with a mada acquirer link in the Kingdom of Saudi Arabia and a fully 3DS authenticated payer outside of the gateway, you must be integrated to WS API version 76 or later and provide the following authentication details in the Authorize or Pay operation to successfully submit a mada co-branded, mada single-badged, or international card transaction:
authentication.3ds2.acsReference: Specifies a reference number that EMVCo assigns to the issuer's Access Control Server (ACS) upon approval of the ACS. This field corresponds to the EMVCo field acsReferenceNumber.authentication.3ds2.dsReference: Specifies a reference number that EMVCo assigns to the Directory Server (DS) upon approval of the DS. This field corresponds to the EMVCo field dsReferenceNumber.authentication.3ds2.acsTransactionId: Specifies a unique transaction identifier that the Access Control Server assignes to identify the 3DS transaction.authentication.time: Specifies the Date and time of the payer authentication. This field corresponds to the EMVCo field purchaseDate.authentication.3ds.acsEci: Specifies the Electronic Commerce Indicator (ECI) value that the issuer's Access Control Server (ACS) provides to indicate the results of the attempt to authenticate the payer.authentication.3ds.authenticationToken: Specifies the base64 encoded value that the issuer generates. This field corresponds to the Authentication Value.authentication.3ds.transactionId: Corresponds to the DS Transaction ID.authentication.3ds2.protocolVersion: Specifies the version of the EMV 3-D Secure protocol that is used to perform 3-D Secure authentication. For example, 2.2.0.authentication.3ds2.transactionStatus: Corresponds to the EMVCo field transStatus.authentication.3ds2.authenticationScheme: For externally authenticated mada co-branded transactions, you must provide either MADA, MASTERCARD or VISA to specify the 3DS Directory Server through which the transaction was authenticated. For externally authenticated mada single-badged transactions, you can provide MADA or not submit this field. For other cards, you can provide the respective authentication scheme or not submit this field.
If you want to perform authentication to only verify the identity of the payer without proceeding to the payment, you must indicate the authentication purpose in the Initiate Authentication request. For example, you may want to authenticate the payer when the payer enters their card details for later use during customer registration or account creation on your website. The ability to complete the authentication process in a non-payment environment enhances payer experience and reduces payer drop-off rates.
To perform a non-payment authentication, provide the following fields in the Initiate Authentication request:
- order.currency: Any currency supported on your acquirer link(s).
- authentication.purpose: Indicates the context in which payer authentication is being requested. You can specify one of the following:
- ADD_CARD: Authentication performed before a payer's card is stored on file either directly by you or using the gateway's tokenization feature. A payment is not being processed.
- MAINTAIN_CARD: Authentication performed before updating details of a payer's card stored on file either directly by you or using the gateway's tokenization feature. A payment is not being processed.
If the authentication scheme does not support the purpose you have requested, the gateway returns
AUTHENTICATION_NOT_SUPPORTEDin the response. Note that by default the gateway sets this field toPAYMENT_TRANSACTIONto allow the authentication to be used for a payment transaction.
Aggregator merchants can enable their sub-merchants to use the Authentication API on the gateway. The sub-merchants are not required to have a contractual relationship with the acquirer nor with the gateway. The aggregator merchant can submit the sub-merchant details required for initiating the authentication via the Initiate Authentication operation. For more information, see Aggregator Support.
The Authentication API records the details of the payer authentication using 3DS2 as a separate AUTHENTICATION transaction on the order.
When you retrieve an order using the Retrieve Order operation or receive a Reporting API response, it may contain an additional AUTHENTICATION transaction. Also, when you use Webhook Notifications, you may receive an additional notification for the AUTHENTICATION transaction.
For details about AUTHENTICATION transactions please refer to the list of response parameters for the Authenticate Payer operation.
You can use network tokens for payer authentication from API v57 onwards. The Mastercard Gateway currently supports processing network tokens obtained from the following tokenization service providers: Mastercard Digital Enablement Service (MDES), Visa Token Service (VTS).
If you have obtained a network token by integrating directly to the network tokenization service provider, then you must supply token details using the following fields:
sourceOfFunds.type=SCHEME_TOKEN: Enables the gateway to identify the source of fund provided in the request as a network token. MDES and VTS are supported from API v51 and v53 respectively.sourceOfFunds.provided.card.number: The network token. Supply the value for the MDES "Token PAN" or the VTS "Token".sourceOfFunds.provided.card.expiry: (optional) The network token expiry.
If you have been enabled for network tokenization by your payment service provider, any request to the gateway for a gateway token will also attempt to generate a corresponding network token for enabled schemes, where supported by the card issuer. The gateway will also attempt network tokenization for any applicable cards already stored in the gateway token repository. The Initiate Authentication request will use the network token if available else the Funding PAN (FPAN) stored against the gateway token will be used. This model currently only supports MDES tokens.
If you have used a payment session (session Id) to store the authentication details, the POST request submitted by the payer's browser to your website on completion of the Authenticate Payer request will be parameterised allowing you to determine the authentication outcome. The individual authentication parameters, for example, authentication.3ds2.transactionStatus.data, may be useful in an advanced integration or if you have the need to provide the authentication data in a payment processed via another gateway. To do this, you can submit a Retrieve Transaction request or choose to decrypt the encrypted authentication data (see the following steps):
- Create a session using the Create Session operation.
- Add relevant data to the session Id (returned in the Create Session response) using the Update Session request.
- Use this session Id in the Initiate Authentication and Authenticate Payer requests.
- The redirect of the payer's browser to your website will contain payer authentication details in the
encryptedDatafield. It is an encrypted JSON object containing the authentication data obtained during the authentication process. It contains the following fields: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
- To decrypt the content returned in the encryptedData.ciphertext field, use the session.aes256Key (returned in the Create Session response) in the GCM mode. The Base64 encoded key is a secret and must be known only by you.
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);
}
}
The Authenticate Payer request can take a large volume of information about the payer and the transaction. For example, you can provide the following data in the request using the fields in the customer.account parameter group, which helps the issuer's ACS to assess the level of risk associated with the activity. This means in the case of legitimate payments it helps the ACS to confirm that the payer is likely to be the actual cardholder.
- Is the payer using an existing account?
customer.account.history.creationDate
- How long has the account existed?
customer.account.history.lastUpdatedcustomer.account.history.passwordLastChanged
- How frequently has the payer shopped with you?
customer.account.history.addCardAttemptscustomer.account.history.annualActivitycustomer.account.history.recentActivitycustomer.account.history.shippingAddressDate
- Have they ordered these items from you previously?
customer.account.history.issuerAuthentication.acsTransactionIdcustomer.account.history.issuerAuthentication.timecustomer.account.history.issuerAuthentication.type
- Have you observed suspicious activity (e.g. failed login attempts) on the account?
customer.account.history.suspiciousActivitycustomer.account.authentication.methodcustomer.account.authentication.time
You can also provide the following recommended fields for each card scheme in the Authenticate Payer request. Note that this list is not definitive and may be subject to change.
| Field | Mastercard | Visa | American Express | Notes |
|---|---|---|---|---|
| shipping.contact.email | - | - | Y | Required to calculate merchant risk |
| shipping.method | - | - | Y | Required to calculate merchant risk |
| order.valueTransfer.amount | - | - | Y | Required to calculate merchant risk. Applicable only to gift cards. |
| order.valueTransfer.numberOfCards | - | - | Y | Required to calculate merchant risk. Applicable only to gift cards. |
| order.valueTransfer.currency | - | - | Y | Required to calculate merchant risk. Applicable only to gift cards. |
| order.supply.preorderAvailabilityDate | - | - | Y | Required to calculate merchant risk |
| order.supply.preorder | - | - | Y | Required to calculate merchant risk |
| order.supply.reorder | - | - | Y | Required to calculate merchant risk |
| order.valueTransfer.accountType | - | Y | - | Required by Visa and by other schemes in certain markets (e.g. Brazil). Not applicable if order.valueTransfer.accountType=NOT_A_TRANSFER |
The gateway provides the authentication status in the transaction.authenticationStatus field. This field may return one of the following values depending on the authentication stage:
AUTHENTICATION_ATTEMPTED: Payer authentication was attempted and a proof of authentication attempt was obtained.AUTHENTICATION_AVAILABLE: Payer authentication is available for the payment method provided.AUTHENTICATION_FAILED: The payer was not authenticated. You should not proceed with this transaction.AUTHENTICATION_NOT_SUPPORTED: The requested authentication method is not supported for this payment method.AUTHENTICATION_NOT_IN_EFFECT: There is no authentication information associated with this transaction.AUTHENTICATION_PENDING: Payer authentication is pending completion of a challenge process.AUTHENTICATION_REJECTED: The issuer rejected the authentication request and requested that you do not attempt authorization of a payment.AUTHENTICATION_REQUIRED: Payer authentication is required for this payment, but was not provided.AUTHENTICATION_SUCCESSFUL: The payer was successfully authenticated.AUTHENTICATION_UNAVAILABLE: The payer was not able to be authenticated due to a technical or other issue.
The length of time payment authentication data is valid for can depend on your use case. Please contact your payment service provider if you need clarification.
To use recurring transaction with authentication, see Credential on File, Cardholder, and Merchant Initiated Transactions.
You can use device payment tokens for payer authentication, from API v55 onwards. Only payment tokens obtained from Google Pay SDK are supported. You can provide an encrypted payment token or the "pan" obtained from a decrypted payment token for payer authentication. The gateway only accepts authentication requests with FPAN, requests with DPANs will be rejected. To supply card details via payment token, provide the following field:
order.walletProvider=GOOGLE_PAYsourceOfFunds.provided.card.devicePayment.paymentToken: Applicable only if payment token is decrypted by the gateway. It's the encrypted payment token obtained from the Google Pay SDK.sourceOfFunds.provided.card.number: Applicable only if payment token is decrypted by you. The value corresponding to the Google Pay JSON Key "pan".
Before initiating the payer authentication, you can obtain a Dynamic Currency Conversion (DCC) rate quote from the DCC provider by submitting the Payment Options Inquiry request.
If the DCC provider has made an offer, you have provided this offer to the payer, and the payer has accepted it, you must include the following in the Initiate Authentication request:
- currencyConversion.requestId as returned in the Payment Options Inquiry response
- currencyConversion.uptake=ACCEPTED
If the payer has declined the offer, in the Initiate Authentication request, indicate:
- currencyConversion.requestId as returned in the Payment Options Inquiry response
- currencyConversion.uptake=DECLINED
If DCC is not required for this transaction, submit the Initiate Authentication request with:
- currencyConversion.uptake=NOT_REQUIRED
If you are configured to use DCC and do not provide currencyConversion.uptake in the Initiate Authentication request, the Initiate Authentication response indicates currencyConversion.uptake=NOT_REQUIRED.
If the payer accepts the DCC offer, payer authentication process uses the payer's currency and the payer's amount. In all other cases, the payer authentication process uses the order amount and the order currency.
You can use the DCC information provided in the Initiate Authentication request on the subsequent payment request by referencing the authentication transaction, that is authentication.transactionId. The DCC information submitted during payer authentication will apply to your payment transaction.
You can also choose to submit the same DCC information for authentication as well as on the subsequent payment transaction.
If the subsequent payment transaction, which references the authentication transaction, contains different DCC information, then the payment transaction is rejected.
- payer authentication resulting in fallback to 3DS1
- merchant initiated authentications including refresh payer authentication.