3D Secure Authentication
3-Domain Secure™ (3-D Secure or 3DS) 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.
3DS, also known as 3DS2 in the CommWeb payment 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 SecureCode™, Verified by Visa™, American Express SafeKey™, Diners Club/Discover ProtectBuy, JCB J/Secure, ITMX Local Switch EMVCo, and mada secure.
Terminology
The following table lists the key terms referenced throughout the 3DS integration documentation.
| Term | Description |
|---|---|
| 3DS JavaScript API | A client-side JavaScript API that allows you to initiate 3DS authentication from the payer's browser using session-based authentication.
This API is used with the Hosted Session 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 3DS 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 are submitted as a form post in a hidden iframe, so that the ACS can collect additional data. |
| Authentication Channel | Location where 3DS 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 3DS 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/certificate/session authentication. |
| Payer Authentication API | A server-side API consisting of two operations, Initiate Authentication and Authenticate Payer, 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. This API is used with the Direct Payment 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. |
| Session Authentication | Authentication using a payment session. This authentication method allows payers to provide their payment details directly to the gateway via a client-side interaction with the gateway, either through a payer's browser or an app on the payer's mobile device. It uses basic HTTP authentication mechanism (similar to password authentication) where you must provide 'merchant.<your gateway merchant ID>' 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) from your server to the gateway server. |
3DS authentication flow
The following diagram illustrates the authentication flow for a payment where the payer is authenticated using 3DS.
The authentication flow for a successful authentication is as follows:
- 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.
- Send the INITIATE AUTHENTICATION request to ask the gateway to check with the card scheme if the card is enrolled for 3DS.
- If 3DS authentication of the payer is available, the gateway returns the authentication details of the supported ACS method call in the response.
- 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.
- Send the AUTHENTICATE PAYER request to ask the gateway to perform the initiated authentication.
- 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.
- Submit the payment for processing by using the AUTHORIZE or PAY request, and includes the 3DS authentication transaction ID in the request.
- Display the order confirmation page to the payer.
authentication.redirect.html that should be included in the payer's' browser through a hidden iframe. This helps to minimise the wait time for payers when they receive a “SERVER_BUSY” error. Adding 3DS to your integration
Prerequisites
- To use the gateway's 3DS authentication service:
- You must be registered with your acquirer to use 3DS.
- Your merchant profile on the gateway must be enabled for at least one 3DS scheme for a supported 3DS version.
- You must use API v57 or later.
3DS authentication modes
- The gateway supports the following 3DS authentication modes:
- Authentication Only: You perform 3DS 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 3DS authentication using this gateway and proceed to submit the payment (using the authentication details) through this gateway.
- Pre-authenticated Payment Transaction: You perform 3DS authentication using an external provider and supply the authentication details when submitting a payment through this gateway.
3DS integration options
The gateway supports the following integration options for 3DS.
| Integration Method | 3DS Integration | When to Use | Supported Authentication Mode |
|---|---|---|---|
| Hosted Checkout | 3DS with Hosted Checkout | This is the easiest integration option. If you support 3DS, the 3DS authentication is automatically handled by the Hosted Payment Page in your Hosted Checkout integration. |
|
| Hosted Session | 3DS JavaScript API | This is a JavaScript integration with which you can initiate 3DS 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 3DS authentication and other 3DS operations directly from the payer's browser, you must first establish the authentication channel where your merchant server must communicate with the gateway server for creating 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). |
|
| Direct Payment | Payer Authentication API | 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. You must perform operations needed for managing the 3DS integration flows directly from your merchant server to the gateway server. The Payer Authentication API also supports payment sessions (see Session Basics). |
|
| Mobile Integration | Embedded in the SDK | If you support 3DS, you can initiate the authentication with a function call and the rest of the process is automatically handled by the SDK. |
|
FAQs
How do I view authentication details in the Merchant Administration?
You can view authentication details for both individual authentications and authentications that proceeded with the payment in the Merchant Administration. Search for the order or transaction in the search page and view the authentication details.
How do I retrieve 3DS authentication results?
If you want to retrieve the authentication results at any stage, use the RETRIEVE TRANSACTION operation.
The fields that are only used during the authentication, for example, authentication.redirect.html, are not persisted in the gateway and, therefore, are not returned.
How do I submit a pre-authenticated payment request?
If you have used an external 3DS MPI (Merchant Plug-In) 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 3DS MPI, all fields are optional. However, if you have the data, provide it:
authentication.3ds.acsEciElectronic Commerce Indicator returned to you in the authentication response message.
-
authentication.3ds.authenticationTokenBase64-encoded value generated by the card issuer returned to you in the authentication response message.
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. -
authentication.3ds.transactionIdUnique transaction identifier generated by the gateway for the 3DS authentication. The field corresponds to the identifier assigned by the scheme directory server.
-
authentication.3ds2.protocolVersionVersion of the 3DS protocol used to perform 3DS authentication, in the format specified by EMVCo. For example, 2.2.0.
-
authentication.3ds2.transactionStatusResult of payer authentication with the issuer.
-
authentication.3ds2.statusReasonCodeCode indicating the reason for the transaction status returned in
authentication.3ds2.transactionStatus. You must provide this whenauthentication.3ds2.transactionStatusreturnsN,U, orR. -
authentication.amountAuthentication amount. You must 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.timeDate and time of the payer's authentication. Check with your PSP before using this field.
If you are an eCommerce 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 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.acsReferenceReference number that EMVCo assigns to the issuer's ACS upon approval of the ACS. This field corresponds to the EMVCo
acsReferenceNumberfield. -
authentication.3ds2.dsReferenceReference number that EMVCo assigns to the Directory Server (DS) upon approval of the DS. This field corresponds to the EMVCo dsReferenceNumber field.
-
authentication.3ds2.acsTransactionIdUnique transaction identifier that the ACS assigns to identify the 3DS transaction.
-
authentication.timeDate and time of the payer authentication. This field corresponds to the EMVCo
purchaseDatefield. -
authentication.3ds.acsEciElectronic Commerce Indicator (ECI) value that the issuer's ACS provides to indicate the results of the attempt to authenticate the payer.
-
authentication.3ds.authenticationTokenBase64-encoded value that the issuer generates. This field corresponds to the Authentication Value.
-
authentication.3ds.transactionIdTransaction ID. This field corresponds to the DS Transaction ID.
-
authentication.3ds2.protocolVersionVersion of the 3DS protocol that is used to perform 3DS authentication. For example, 2.2.0.
-
authentication.3ds2.transactionStatusTransaction status. This field corresponds to the EMVCo
transStatusfield. -
authentication.3ds2.authenticationSchemeAuthentication scheme. For externally authenticated mada co-branded transactions, you must provide either
MADA,MASTERCARD, orVISAto specify the 3DS DS through which the transaction was authenticated. For externally authenticated mada single-badged transactions, you can provideMADA, or not submit this field. For other cards, you can provide the respective authentication scheme or not submit this field.
How can I submit a non-payment authentication request?
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.
- To perform a non-payment authentication, provide the following fields in the INITIATE AUTHENTICATION request:
order.currencyAny 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 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_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.
How to use 3DS as an aggregator merchant?
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 nor 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.
How are 3DS interactions represented on the gateway?
The Payer Authentication API records the details of the payer authentication using 3DS 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 operation or receive a Reporting API response, it can contain an additional AUTHENTICATION transaction. Also, when you use Webhook notifications, you can receive an additional notification for the AUTHENTICATION transaction.
Can I use network tokens as source of funds in payer authentication?
You can use network tokens for payer authentication from API v57 onwards. For detailed information, see Network Tokenization.
If your 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.
Can I use device payment tokens as source of funds in payer authentication?
You can use device payment tokens for payer authentication from API v55 onwards. Only payment tokens obtained from the 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 are rejected. To supply card details through a payment token, provide the following fields:
-
order.walletProvider = GOOGLE_PAY -
sourceOfFunds.provided.card.devicePayment.paymentTokenEncrypted payment token obtained from the Google Pay SDK. Applicable only if the payment token is decrypted by the gateway.
-
sourceOfFunds.provided.card.numberGoogle Pay JSON Key PAN. Applicable only if the payment token is decrypted by you.
How do I implement advanced payment session integrations?
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, for example, authentication.3ds2.transactionStatus.data, can be useful in an advanced integration or if you have the 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:
- 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 the session ID in the INITIATE AUTHENTICATION and AUTHENTICATE PAYER requests.
- The redirect of the payer's browser to your web site contains 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.id
encryptedData.nonceencryptedData.tag
- To decrypt the content returned in the
encryptedData.ciphertextfield, use thesession.aes256Keyfield 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.
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);
}
}
What can I do to increase the chances of frictionless flow?
The AUTHENTICATE PAYER request can include a lot 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 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.
Recommended Fields for Each Card Scheme in AUTHENTICATE PAYER
| 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 (for example, Brazil). Not applicable if order.valueTransfer.accountType = NOT_A_TRANSFER. |
How do I determine the authentication status?
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_ATTEMPTEDPayer authentication was attempted, and a proof of authentication attempt was obtained.
AUTHENTICATION_AVAILABLEPayer authentication is available for the payment method provided.
AUTHENTICATION_FAILEDPayer was not authenticated. Do not proceed with this transaction.
AUTHENTICATION_NOT_SUPPORTEDRequested authentication method is not supported for this payment method.
AUTHENTICATION_NOT_IN_EFFECTThere is no authentication information associated with this transaction.
AUTHENTICATION_PENDINGPayer authentication is pending completion of a challenge process.
AUTHENTICATION_REJECTEDIssuer rejected the authentication request and requested that you do not attempt authorization of a payment.
AUTHENTICATION_REQUIREDPayer authentication is required for this payment, but was not provided.
AUTHENTICATION_SUCCESSFULPayer was successfully authenticated.
AUTHENTICATION_UNAVAILABLEPayer 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.
How to Use Dynamic Currency Conversion with Payer Authentication?
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 and you have provided this offer to the payer, you must indicate the payer reaction in the INTIATE AUTHENTICATION request:
- If the payer has accepted the offer, use:
currencyConversion.requestIdas returned in the PAYMENT OPTIONS INQUIRY responsecurrencyConversion.uptake = ACCEPTED
- If the payer has declined the offer, use:
currencyConversion.requestIdas returned in the PAYMENT OPTIONS INQUIRY responsecurrencyConversion.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.
authentication.purpose = REFRESH_AUTHENTICATION).