# EMV 3-D Secure Authentication source: https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md 3-Domain Secure™ (EMV 3-D Secure) is a security protocol that adds an additional layer of security to online purchases by requiring cardholders to authenticate themselves with the card issuer when making payments. It helps to prevent unauthorized online transactions, reducing the risk of fraud, and can protect the merchant from chargebacks if the transaction is authenticated successfully. When a cardholder makes an online purchase, the issuer uses its Access Control Server (ACS) to validate the cardholder's identity. EMV 3-D Secure, also known as 3DS2 in the Mastercard Gateway, is the latest version of the security protocol, designed to enhance security in online purchases while providing frictionless checkouts to payers who are considered low risk by the ACS. The ACS determines the risk using information provided by the merchant, browser fingerprinting, and previous interactions with the payer. The ACS subjects the payer to a challenge (for example, entering a PIN) only where additional verification is required to authenticate the payer, thereby providing increased conversion rates. Supported authentication schemes include: * Mastercard Identity Check * Visa Secure * American Express SafeKey™ * Diners Club/Discover ProtectBuy * JCB J/Secure * ITMX Local Switch EMVCo * mada secure * UnionPay * Jaywan SecureNxt * Verve SafeToken ## Terminology {#terminology} The following table lists the key terms referenced throughout the EMV 3-D Secure integration documentation. | Term | Description | |-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | EMV 3-D Secure JavaScript API | A client-side JavaScript API that allows you to initiate EMV 3-D Secure authentication from the payer's browser using session-based authentication. This API is used with the [Hosted Session](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/index.md) integration method. | | Access Control Server (ACS) | A component that operates in the issuer domain, which verifies whether authentication is available for a card number and device type, and authenticates specific transactions. | | ACS Method Call | A call that allows the ACS to gather additional data to determine the risk score for the payer. When EMV 3-D Secure is available and when the ACS call details are returned in the response after initiating the authentication, these details are passed to the payer's browser, which is submitted as a form post in a hidden iframe, so that the ACS can collect additional data. | | Authentication Channel | Location where EMV 3-D Secure authentication is taking place, in the payer's browser, in an app on the payer's mobile device, or in your system with no payer present to interact. | | Authentication Purpose | Purpose of the EMV 3-D Secure authentication action. Usually, you want either to authenticate the payer to process a payment for a specific card or to process a non-payment authentication where you simply verify a new card the payer wants to store in your app or web site for future payments. | | Challenge Flow | An authentication flow where the payer is redirected to the ACS and is required to respond to a challenge to identify themselves, because the ACS does not have sufficient payer information to deem the payer as low risk. | | Frictionless Flow | An authentication flow where the payer is not required to respond to a challenge because the ACS deems the payer as low risk. | | Merchant Authentication | A mechanism that allows the merchant to authenticate API requests to the gateway, for example, [password](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/secure-int-pw-cert/index.md#password-authentication)/[certificate](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/secure-int-pw-cert/index.md#certificate-authentication)/[session authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/secure-int-pw-cert/index.md#session-authentication). | | Payer Authentication API | A server-side API consisting of two operations, [Initiate Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) and [Authenticate Payer](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication), that must be submitted from your server to the gateway server. It can also be used as a client-side API using session-based [authentication](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/index.md). This API is used with the [Direct Payment](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/direct-payment/index.md) integration method. | | Payment Session | A payment session, or simply session, is a temporary container for any request fields and values of operations that reference a session. You can use it in an operation to reference the request fields and values than providing them directly in the operation request. When the gateway receives an operation that references a session, it forms the final request by combining the request fields in the session and those supplied directly in the request. For more information, see [Session Basics](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/integrate-hosted-session/create-payment-session/index.md). | | Session Authentication | Authentication using a payment session. This [authentication](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/index.md) method allows payers to provide their payment details directly to the gateway through a client-side interaction with the gateway, either through a payer's browser or an app on the payer's mobile device. It uses a basic HTTP authentication mechanism (similar to password authentication) where you must provide a 'merchant.' in the **userid** portion and the session ID in the **password** portion. To use this authentication type, you must first create a session by submitting a session request (see [Create session](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session)) from your server to the gateway server. | ## EMV 3-D Secure authentication flow {#emv-3-d-secure-authentication-flow} The following diagram illustrates the authentication flow for a payment where the payer is authenticated using EMV 3-D Secure. ![](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/emv3DS.png) The authentication flow for a successful authentication is as follows: 1. A payer browses your web site, selects one or more products, proceeds to the payment page, and selects to pay with a 3DS-supported card. 2. Send the INITIATE AUTHENTICATION request to ask the gateway to check with the card scheme if the card is enrolled for EMV 3-D Secure. 3. If EMV 3-D Secure authentication of the payer is available, the gateway returns the authentication details of the supported ACS method call in the response. Warning: The INITIATE AUTHENTICATION response contains authentication.redirect.html that should be included in the payer's' browser through a hidden iframe. This helps to minimize the wait time for payers when they receive a "SERVER_BUSY" error. 4. Submit the ACS method call details as a form post in a hidden iframe, so that the ACS can initiate the authentication and collect additional data about the payer. 5. Send the AUTHENTICATE PAYER request to ask the gateway to perform the initiated authentication. Warning: The result for the ACS method call initiated through the form post is not provided automatically and your app must send the AUTHENTICATE PAYER request to get a response. 6. The gateway provides you with the authentication details based on the authentication flow: * Frictionless flow Where the authentication is complete: The gateway redirects the payer to your website. * Challenge flow Where payer interaction is required to complete the authentication: If the issuer requires the payer to respond to a challenge, your app redirects the payer's web browser to the ACS, which presents its authentication UI. The issuer returns the authentication result to the gateway. The gateway redirects the payer directly to your web site. 7. Submit the payment for processing by using the [AUTHORIZE](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) or [PAY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) request and includes the EMV 3-D Secure authentication transaction ID in the request. 8. Display the order confirmation page to the payer. ## Adding EMV 3-D Secure to your integration {#adding-emv-3-d-secure-to-your-integration} ### Prerequisites {#prerequisites} To use the gateway's EMV 3-D Secure authentication service: * Be registered with your acquirer to use the EMV 3-D Secure. * Your merchant profile on the gateway must be enabled for at least one EMV 3-D Secure scheme for a supported EMV 3-D Secure version. * Use API v57 or later. ### EMV 3-D Secure authentication modes {#emv-3-d-secure-authentication-modes} The gateway supports the following EMV 3-D Secure authentication modes: * Authentication only: You perform EMV 3-D Secure authentication using the gateway. You can choose to submit the payment (using the authentication details) at a later stage through this gateway or another gateway. * Authentication and payment transaction: You perform EMV 3-D Secure authentication using this gateway and proceed to submit the payment (using the authentication details) through this gateway. * Pre-authenticated payment transaction: You perform EMV 3-D Secure authentication using an external provider and supply the authentication details when submitting a payment through this gateway. ### EMV 3-D Secure integration options {#emv-3-d-secure-integration-options} The gateway supports the following integration options for EMV 3-D Secure. | Integration Method | EMV 3-D Secure Integration | When to Use | Supported Authentication Mode | |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------| | Hosted Checkout | [EMV 3-D Secure with Hosted Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-hosted-checkout/index.md) | This is the easiest integration option. If you support EMV 3-D Secure, the EMV 3-D Secure authentication is automatically handled by the Hosted Payment Page in your Hosted Checkout integration. | * Authentication only * Authentication and payment transaction | | Hosted Session | [EMV 3-D Secure JavaScript API](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-js-api/index.md) | This is a JavaScript integration with which you can initiate EMV 3-D Secure authentication from your web site's payment page. Use this option if you want to allow the payer to submit their payment details directly to the gateway from the browser. To initiate EMV 3-D Secure authentication and other EMV 3-D Secure operations directly from the payer's browser, you must first establish the authentication channel where your merchant server must communicate with the gateway server to for create a session on the gateway. The gateway-generated session ID is then included in all browser-initiated authentication requests as the password field (see [Authentication Options](https://developer.mastercard.com/mastercard-gateway/documentation/getting-started/authentication-options/index.md). | * Authentication only * Authentication and payment transaction | | Direct Payment | [Payer Authentication API](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md) | This is a server-side integration option that gives you total control over your integration but requires the highest integration effort. Use this option if you are required to customize API interactions between the payer's browser and the gateway. Perform operations needed for managing the EMV 3-D Secure integration flows directly from your merchant server to the gateway server. The Payer Authentication API also supports payment sessions (see [Session Basics](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/integrate-hosted-session/create-payment-session/index.md)). | * Authentication only * Authentication and payment transaction | | Mobile Integration | [Embedded in the SDK](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/3d-secure-auth/index.md) | If you support EMV 3-D Secure, you can initiate the authentication with a function call, and the rest of the process is automatically handled by the SDK. | * Authentication only * Authentication and payment transaction | ## FAQs {#faqs} EMV 3-D Secure uses an iFrame implementation that requires the use of the ACS URL from the issuing bank. As the list of URLs used by different card issuers keeps changing, it is not possible to set a fixed security policy that works for all of them when using EMV 3-D Secure. If you are using EMV 3-D Secure in your integration, we recommend you allow all websites to load in frames by using frame-src \*. This helps make sure all the necessary EMV 3-D Secure URLs will work, even though they can vary. 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 retrieve the authentication results at any stage, use the [RETRIEVE TRANSACTION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation. The fields that are only used during the authentication, for example, `authentication.redirect.html`, do not persisted in the gateway and, therefore, are not returned. If you have used an external EMV 3-D Secure server to authenticate the payer, you must pass information about the authentication result in the authentication object of the AUTHORIZE or PAY operation. As the status of the transaction determines whether specific fields were provided to you by the external EMV 3-D Secure server, all fields are optional. However, if you have the data, provide it: * `authentication.3ds.acsEci` Electronic Commerce Indicator returned to you in the authentication response message. * `authentication.3ds.authenticationToken` Base64-encoded value generated by the card issuer returned to you in the authentication response message. * `authentication.3ds.transactionId` Unique transaction identifier generated by the gateway for the EMV 3-D Secure authentication. The field corresponds to the identifier assigned by the scheme Directory Server. * `authentication.3ds2.protocolVersion` Version of the EMV 3-D Secure protocol used to perform EMV 3-D Secure authentication, in the format specified by EMVCo. For example, 2.2.0. * `authentication.3ds2.transactionStatus` Result of payer authentication with the issuer. * `authentication.3ds2.statusReasonCode` Code indicating the reason for the transaction status returned in authentication.3ds2.transactionStatus. Provide this when authentication.3ds2.transactionStatus returns N, U, or R. * `authentication.amount` Authentication amount. Provide values in this field when the authentication amount differs from the order.amount. Check with your Payment Service Provider (PSP) before using this field. * `authentication.time` Date and time of the payer's authentication. Check with your PSP before using this field. 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 the gateway, you must be integrated to API v76 or later. 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 from version 76 onwards: * `authentication.3ds2.acsReference` Reference number that EMVCo assigns to the issuer's ACS upon approval of the ACS. This field corresponds to the EMVCo acsReferenceNumber field. * `authentication.3ds2.dsReference` Reference number that EMVCo assigns to the Directory Server (DS) upon approval of the DS. This field corresponds to the EMVCo dsReferenceNumber field. * `authentication.3ds2.acsTransactionId` Unique transaction identifier that the ACS assigns to identify the EMV 3-D Secure transaction. * `authentication.time` Date and time of the payer authentication. This field corresponds to the EMVCo purchaseDate field. * `authentication.3ds.acsEci` Electronic Commerce Indicator (ECI) value that the issuer's ACS provides to indicate the results of the attempt to authenticate the payer. * `authentication.3ds.authenticationToken` Base64-encoded value that the issuer generates. This field corresponds to the Authentication Value. * `authentication.3ds.transactionId` Transaction ID. This field corresponds to the DS Transaction ID. * `authentication.3ds2.protocolVersion` Version of the EMV 3-D Secure protocol that is used to perform EMV 3-D Secure authentication. For example, 2.2.0. * `authentication.3ds2.transactionStatus` Transaction status. This field corresponds to the EMVCo transStatus field. * `authentication.3ds2.authenticationScheme` Authentication scheme. For externally authenticated mada co-branded transactions, you must provide either MADA, Mastercard, or VISA to specify the EMV 3-D Secure DS 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, if you want to authenticate the payer when the payer enters their card details for later use during customer registration or account creation on your web site. The ability to complete the authentication process in a non-payment environment enhances payer experience and reduces payer drop-off rates. Warning: The authentication details from a non-payment authentication cannot be used to claim chargeback liability in a payment transaction. If you provide the non-payment authentication details in an actual payment transaction later, the gateway rejects the request. To perform a non-payment authentication, provide the following fields in the INITIATE AUTHENTICATION request: * `order.currency` Any currency supported on your acquirer links. * `authentication.purpose` Context in which payer authentication is being requested. You can specify one of the following: * `ADD_CARD`: Authentication is 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 is 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_SUPPORTED in the `authenticationStatus` response field. By default, the gateway sets this field to PAYMENT_TRANSACTION to allow the authentication to be used for a payment transaction. Aggregator merchants can enable their sub-merchants to use the Payer Authentication API on the gateway. The sub-merchants are not required to have a contractual relationship with the acquirer or with the gateway. The aggregator merchant can submit the sub-merchant details required for initiating the authentication through the INITIATE AUTHENTICATION operation. For more information, see [Aggregator](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/multi-party-payment-model/aggregator/index.md). The Payer Authentication API records the details of the payer authentication using EMV 3-D Secure as a separate AUTHENTICATION transaction on the order. For details about AUTHENTICATION transactions, refer to the list of response fields for the AUTHENTICATE PAYER operation. When you retrieve an order using the [RETRIEVE ORDER](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation or receive a [Reporting](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/data-and-reporting/reporting/index.md) API response, it can contain an additional AUTHENTICATION transaction. Also, when you use [Webhook](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/webhook-noti/index.md) notifications, you can receive an additional notification for the AUTHENTICATION transaction. You can use network tokens for payer authentication from API v57 onwards. For detailed information, see [Network Tokenization](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/tokenization/network-tokenization/index.md). If your Payment Service Provider (PSP) has enabled you for network tokenization, any request to the gateway for a gateway token also attempts to generate a corresponding network token for enabled schemes, where supported by the card issuer. The gateway also attempts network tokenization for any applicable cards already stored in the gateway token repository. The INITIATE AUTHENTICATION request uses the network token, if available. Otherwise, the Funding PAN (FPAN) stored against the gateway token is used. This model currently only supports MDES tokens. You can use device payment tokens for payer authentication from API v55 onwards. Only payment tokens obtained from the [Google Pay](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/google-pay/index.md) 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 are rejected. To supply card details through a payment token, provide the following fields: * `order.walletProvider = GOOGLE_PAY` * `sourceOfFunds.provided.card.devicePayment.paymentToken` Encrypted payment token obtained from the Google Pay SDK. Applicable only if the payment token is decrypted by the gateway. * `sourceOfFunds.provided.card.number` Google Pay JSON Key PAN. Applicable only if the payment token is decrypted by you. 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 web site on completion of the AUTHENTICATE PAYER request is parameterized allowing you to determine the authentication outcome. The individual authentication fields can be useful in an advanced integration or if you need to provide the authentication data in a payment processed through another gateway. To do this, you can submit a RETRIEVE TRANSACTION request or choose to decrypt the encrypted authentication data as follows: 1. Create a session using the CREATE SESSION operation. 2. Add relevant data to the session ID (returned in the CREATE SESSION response) using the UPDATE SESSION request. 3. Use the session ID in the INITIATE AUTHENTICATION and AUTHENTICATE PAYER requests. 4. The redirect of the payer's browser to your web site contains payer authentication details in the encryptedData field. It is an encrypted JSON object containing the authentication data obtained during the authentication process. It contains the following fields: * `encryptedData.ciphertext` * `authentication.3ds.acsEci` * `authentication.3ds.authenticationToken` * `authentication.3ds2.protocolVersion` * `authentication.3ds.transactionId` * `authentication.3ds2.transactionStatus` * `authentication.3ds2.dsTransactionId` * `transaction.authenticationStatus` * `authentication.3ds2.statusReasonCode` * `sourceOfFunds.provided.card.number` * `sourceOfFunds.provided.card.expiry.month` * `sourceOfFunds.provided.card.expiry.year` * `sourceOfFunds.token` * `order.id` * `transaction.id` * `encryptedData.nonce` * `encryptedData.tag` 5. To decrypt the content returned in the encryptedData.ciphertext field, use the session.aes256Key field value (returned in the CREATE SESSION response) in the GCM mode. The base64-encoded key is a secret and must be known only by you. **Decrypting Example** ```java 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 include much 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 object, which helps the issuer's ACS to assess the level of risk associated with the activity. With 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.lastUpdated` * `customer.account.history.passwordLastChanged` * How frequently has the payer shopped with you? * `customer.account.history.addCardAttempts` * `customer.account.history.annualActivity` * `customer.account.history.recentActivity` * `customer.account.history.shippingAddressDate` * `customer.account.history.issuerAuthentication.acsTransactionId` * `customer.account.history.issuerAuthentication.time` * `customer.account.history.issuerAuthentication.type` * Have you observed suspicious activity (for example, failed login attempts) on the account? * `customer.account.history.suspiciousActivity` * `customer.account.authentication.method` * `customer.account.authentication.time` You can also provide the following recommended fields for each card scheme in the AUTHENTICATE PAYER request. This list is not definitive and may be subject to change. **Mandatory and recommended fields for each card scheme in AUTHENTICATE PAYER** | Fields | Description | Requirement Status | |----------------------------------------------------------------------------------|-----------------------------------------|--------------------| | `device.ipAddress` | Browser IP Address | Mandatory | | `device.browserDetails.screenHeight` | Browser Screen Height | Mandatory | | `device.browserDetails.screenWidth` | Browser Screen Width | Mandatory | | `customer.email` | Payer Email Address | Mandatory | | `customer.mobilePhone` | Payer Phone Number | Mandatory | | `customer.firstName` | Payer first name | Mandatory | | `customer.lastName` | Payer last name | Mandatory | | `billing.address.city` | Payer Billing Address City | Recommended | | `billing.address.country` | Payer billing address country | Recommended | | `billing.address.company` / `billing.address.street` / `billing.address.street2` | Cardholder Billing Address Line 1 | Recommended | | `billing.address.postcodeZip` | Cardholder Billing Address Postal Code | Recommended | | `billing.address.stateProvinceCode` | Cardholder Billing Address State | Recommended | | `device.ipAddress` | Common Device Identification Parameters | Recommended | Warning: Supply as much of this data as possible, as it increases the likelihood that the ACS offers frictionless authentication, which greatly improves the payer experience resulting in a more streamlined checkout. This table describes the Authenticate Payer `authentication.3ds2.statusReasonCode` response values, which can help to understand why an EMV 3-D Secure authentication may have failed. Note that it is for informational purposes only and that this is not an exhaustive list, which may be updated over time and can change depending on the card scheme that was used to authenticate the transaction. | Value | Description | |-------|---------------------------------------------------------------------------------------------------------------| | 01 | Card authentication failed | | 02 | Unknown Device | | 03 | Unsupported Device | | 04 | Exceeds authentication frequency limit | | 05 | Expired card | | 06 | Invalid card number | | 07 | Invalid transaction | | 08 | No Card record | | 09 | Security failure | | 10 | Stolen card | | 11 | Suspected fraud | | 12 | Transaction not permitted to cardholder | | 13 | Cardholder not enrolled in service | | 14 | Transaction timed out at the ACS | | 15 | Low confidence | | 16 | Medium confidence | | 17 | High confidence | | 18 | Very High confidence | | 19 | Exceeds ACS maximum challenges | | 20 | Non-Payment transaction not supported | | 21 | 3RI transaction not supported | | 22 | ACS technical issue | | 23 | Decoupled Authentication required by ACS but not requested by 3DS Requestor | | 24 | 3DS Requestor Decoupled Max Expiry Time exceeded | | 25 | Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt | | 26 | Authentication attempted but not performed by the cardholder | | 27-79 | Reserved for EMV future use (values invalid until defined by EMV) | | 80-99 | Reserved for DS use | The gateway provides the authentication status in the `transaction.authenticationStatus` field. This field can 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` Payer was not authenticated. Do not proceed with this transaction. * `AUTHENTICATION_NOT_SUPPORTED` 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` 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` Payer was successfully authenticated. * `AUTHENTICATION_UNAVAILABLE` Payer was not able to be authenticated due to a technical or other issue. The length of time the payment authentication data is valid for can depend on your use case. Contact your PSP if you need clarification. To use a recurring transaction with authentication, see [Credential on File Transactions](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/cred-file-transc/index.md). Before initiating the payer authentication, you can obtain a [Dynamic Currency Conversion](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/dynamic-currency-conversion/index.md) (DCC) rate quote from the DCC provider by submitting the [PAYMENT OPTIONS INQUIRY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#gateway) request. If the DCC provider has made an offer and you have provided this offer to the payer, you must indicate the payer reaction in the [INTIATE AUTHENTICATION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) request: If the payer has accepted the offer, use: * `currencyConversion.requestId` as returned in the PAYMENT OPTIONS INQUIRY response * `currencyConversion.uptake = ACCEPTED` If the payer has declined the offer, use: * `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, the 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 (`authentication.transactionId`). The DCC information submitted during payer authentication applies to your payment transaction. You can also submit the same DCC information in the subsequent payment transactions as in the authentication, if you want to. However, if the subsequent payment transaction both references the authentication transaction and contains DCC information that differs from the authentication, the payment transaction is rejected. Warning: Dynamic Currency Conversion is not supported for merchant-initiated authentications including refresh payer authentication (authentication.purpose = REFRESH_AUTHENTICATION). Use the `authentication.challengePreference` field to tell the issuer whether you want the customer to complete a challenge during authentication. This field supports the following options: * **CHALLENGE_MANDATED** You require the issuer to present a challenge to the customer. * **CHALLENGE_PREFERRED** You prefer the issuer to present a challenge, but you do not require it. * **NO_CHALLENGE** You prefer that the issuer does not present a challenge. * **NO_PREFERENCE** You have no preference. The issuer decides whether to present a challenge. * **REQUEST_TRUSTED_MERCHANT_LISTING** You ask the issuer to present a challenge and prompt the customer to add you as a trusted merchant for that card. If the customer agrees, the response includes `authentication.psd2.trustedMerchantStatus = ON_LIST`. This allows you to request a trusted‑merchant exemption for future payments made with the same card. This option is not supported in all regions. Refer to the integration guidelines for details. #### Integration {#integration} * Merchants using **Direct Payment** or **Hosted Session** include this field in the [AUTHENTICATION_PAYER](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) API request. * Merchants using **Hosted Checkout** include this field in the [INITIATE_CHECKOUT](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) API request. #### Reducing customer friction {#reducing-customer-friction} To reduce challenges, send as much relevant data as possible in the [AUTHENTICATION_PAYER](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) or [INITIATE_CHECKOUT](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) request. Providing more information helps the issuer's ACS assess transaction risk more accurately and can reduce the likelihood of a challenge. #### MTF testing limitations {#mtf-testing-limitations} Due to limitations in the ACS Emulator, you cannot test `authentication.challengePreference` in MTF. Test cards always return the challenge behavior defined on the 3DS Test Cards page, regardless of the value you set.