Frequently Asked Questions (FAQ)
Netcetera environments and integration
3DS Flow
EMV 3DS 2.3.1
Merchants’ onboarding & configuration
User Management
Visa DAF program
JSON Web Tokens (JWT) Authentication (NOT available for new customers)
Netcetera environments and integration
I have access to the demo/test environment. What can I use the demo/test environment for?
What is the difference between Preview and Production environments?
Production is the live production environment which is connected to the production Directory Servers of the payment schemes and the production issuer ACS.
You can use our Mastercard merchant testing platform if you wish to run production tests with Mastercard issued cards. Read more info about our unique Mastercard PSD2 Merchants testing platform: Mastercard merchant testing.
I am setup/onboarded on preview and production. How can I add a new (additional) Results Response Notification URL?
How do I use the CSR file?
Signed CSR file is provided to you when we onboarded you on our cloud payment platform preview/production environment. This is an SSL certificate you need to put in each request you send towards our 3DS server. There’re two different certificates – one for preview and another one for production. More on this here.
We have Sandbox, UAT and QA environments, prior to moving to the Production environment. How does this relate to Netcetera 3DS Server SaaS setup?
On Netcetera side, there are two environments – Preview and Production. More information here. Basically, Preview environment covers the needs and activities done in Sandbox, UAT and QA. If you still wish to have separate environments on Preview for each Sandbox, UAT and QA, please contact your Netcetera representative.
Which schemes is the 3DS Server certified with?
Please check the Compliance page containing all schemes’ compliance letters.
Can I have my own test cards and scenarios configured on the Preview environment?
Yes, this is possible. For requests like these, please open a ticket at the Netcetera service portal.
I tried sending a request, but I got “400 Bad Request. The server detected a syntax error in your request. Check your request and all parameters.” What does it mean?
Are you sending the 3DS Organization ID in the header of the request? For PREV and PROD you must not do this since the Organization ID is resolved from the Common Name of your client certificate. When you are sending the Organization ID in the header, our WAF is blocking the request. If yes, please try again with no header.
I’m starting with integration with 2.X APIs on PREV; please tell me about specific endpoints and how to proceed with authentication + examples.
If you are integrating 3DS 2.0, here are the main endpoints and flow regarding that protocol version. For our PREV environment, please use the 3DS endpoint we provided to you as a base URL. Afterwards, the main endpoints for 3DS 2.0 are as follows (described in the documentation here). For example, if you wish to send an authentication request, you should use the endpoint https://[Netcetera provided endpoint]/3ds/authentication. The flow of the 3DS 2.0 protocol is represented in a diagram here. That page also gives more information about the individual calls in the flow.
This page gives an overview of the Authentication Request and Response Models. An example JSON of an Authentication Request can be found on the same page > Authentication Request JSON Samples. Please make sure to also pass the certificate (.pem) file we have shared with you, since this is our way of authenticating you and allowing access to our PREV environment.
Does the 3DS Server comply with GDPR?
Netcetera 3DS Server is compliant with GDPR.
The Netcetera 3DS Server Protocol application logs all 3-D Secure protocol messages in log files. However, the application does not store sensitive data (authenticationValue, sdkEncData, sdkEphemPubKey) and masks all PII data before storing the protocol message to the log file. PII data include: cardholder account number (PAN), browserIP, cardholderName, email, shipping and billing address data (city, country, state, address, post code) and phone numbers. The cardholder account number is masked in a format that first 6 and last 4 digits are plain, and all other are replaced with a star (123456****4321). Other PII data fields are fully masked with star characters. All non-sensitive data are stored as plain-text values.
3DS Flow
What exemptions does the 3DS Server support?
Netcetera 3DS Server supports all exemptions via: Message extensions for Mastercard 2.1+ version and Authentication Request for all schemes 2.2.0 version programs. On the following link you can find details on the exemptions usage:
Authentication Request Json Samples > Authentication Request indicating SCA exemptionPlease find in the “Exemptions guide” document additional information on the exemptions.
Will the server fallback the transactions from 3DS 2.x to 3DS 1.0?
Netcetera 3DS Server does not automatically fallback the transactions from 3DS 2.x to 3DS 1.0. The client should develop the APIs and the logic for initiation of the transactions with 1.0 in case of fall back. Two different APIs should be developed by the client for integration against EMV 3DS 2.x and 3DS 1.0. After the Preparation Request is initiated by the 3DS Server, the DS returns a list of card ranges with supported protocol versions, as part of the Preparation Response. Subsequently, the versioning request can be used to check whether the card is registered for 3DS 2.x. Given a versioning request, the 3DS Server matches the cardholder account number with the ranges returned from each configured directory server. For more details, please see the technical documentation sample for this case.
What does TransStatusReason=82 mean?
TransStatusReason=82 is a Mastercard specific value. It indicates that a challenge is mandated but could not be performed. This happens when in the request, messageCategory = 01 (PA, Payment) and threeDSRequestorChallengeInd = 04 (challenge mandated) but the ACS is unavailable, resulting in the DS throwing the error with transStatusreason = 82. The given issue needs to be troubleshooted with the ACS directly, such that they can check the given query and the reason for the provided response.
My authentication requests are failing with the error "errorDescription: "A message element required is missing from the message."; "errorDetail”: "threeDSRequestorName, threeDSRequestorID"
According to the EMVCo specification, 3DS Requestor ID and Name are unique identifiers, provided by the Schemes to each 3DS Requestor on an individual basis. Therefore, these two values should be either configured for each Merchant Acquirer in the Admin UI, or should be passed in the transaction payload as part of the Merchant data.
Authentication Request Json Samples > Authentication Request without merchantConfigurationIdEvery scheme has its own instructions about the format of these values. More scheme-specific details are provided here: 3DS Requestor Data.
We recommend following the pre-defined formats. Here, the number of characters and some special characters (if it contains any) are important and need to be considered.
I have one and the same card/same BIN which is co-branded (Global- and domestic scheme, i.e., it’s both Visa and CB). Through which scheme will it be processed?
The schemeId is not a mandatory field, however, in case a card is co-branded and hence found in more than one scheme card range, we need you to send the appropriate schemeId for the transaction. Otherwise, we cannot resolve which scheme we should process the request/transaction with.
From 2.5.3.0 version of Netcetera 3DS Server, in the case when the BIN is found in two schemes’ card ranges, (domestic and global) and if the schemeId is not provided, we will process the transaction via the global scheme network. That means, if you want to process through a domestic scheme, you must provide the schemeId.
Does the 3DS Server perform BIN matching that confirms if a card is enrolled in 3DS 2?
The 3DS Server checks if a card range is enrolled in 3DS 2.x using the versioning flow. If the card range is enrolled, the transaction should be initiated with the corresponding 2.x protocol version. If it is not enrolled, the transaction should be initiated using 3DS 1.0. More information regarding the versioning method can be found here: 3DS Versioning.
Please can you provide more details on 3DS 2 Flow?
The 3DS 2.0 flow is described in more detail here: 3DS 2.x API.
The first step in the flow is 3DS Versioning. The Versioning Response contains, among other fields, the threeDSMethodURL and threeDSMethodDataForm. Using the threeDSMethodData value found in the threeDSMethodDataForm, a request should be initiated to the threeDSMethodURL via an iframe.
Please see below an example of the threeDSMethodData form in the Versioning Response:
After the method completion, the Authentication flow is the next step. The transStatus field of the Authentication Response will indicate whether the transaction is frictionless or requires a challenge (transStatus='C'). In case of challenge, the base64EncodedChallengeRequest field from the Authentication Response should be taken, and a request initiated to the acsURL via an iframe. Here you can see authentication response samples.
After the challenge has been completed, the 3DS Server receives a Results Request from the DS, and generates a Result Response which is sent to the URL configured in the Admin UI. Simultaneously, a final Challenge Response message is sent from the ACS.
For more info on the implementation of browser based flow the Netcetera 3DS Web SDK can be used.
Question regarding Browser based 3DS - can we skip step 4: Gather Device Information?
According to the EMVCo specification, the link between the Browser and the ACS for the 3DS Method is opened from a hidden iframe as part of the check-out page. It is used for the ACS to gather device information to be returned to the ACS. This includes the 3DS Server Transaction ID which enables the ACS to carry the information to the correct transaction. The 3DS Method allows for additional browser information to be gathered by an ACS prior to receiving the AReq message, to help facilitate the transaction risk assessment.
For the versioning responses that contain a 3DS Method URL, the 3DS Requestor should invoke the 3DS Method. The 3DS Method call should occur in advance of the AReq message, for the same transaction being sent to the ACS. The ACS will then interact with the Cardholder browser via the HTML iframe and then store the applicable values with the 3DS Server Transaction ID for use when the AReq message is received containing the same 3DS Server Transaction ID.
This means, that according to the specification, wherever you get a 3DS Method URL in the Versioning Response from the 3DS Server the browser should initiate a request to that URL using the threeDSMethodData that is also available in the response via an iframe.
What is the purpose of the 3DS Method flow and how can I use it?
Within the 3DS Method Request form, which is included in the versioning response, valuable information is requested to be sent from the Browser directly to the ACS. This information contains information about browser type, browser IP, browser language and many other information which help the ACS to apply risk transaction analysis. This risk assessment possibility increases the chance of a frictionless authentication, enabling a smoother experience for the user and a higher conversion rate. This is especially the case if a user shops more often with the same device, ideally with the same merchant. Our 3DS Server product provides the 3DS Method Request form and is offered as 3DS Web SDK lightweight JavaScript. It can easily be installed by importing the JavaScript in the html page.
3DS Method Flow: The merchant sends a versioning request to the 3DS Server to find out whether a specific card is enrolled for 3DS 2.x. If this is true, then the 3DS Server will include the 3DS Method form within the Versioning Response including the ACS URL to the browser so that the browser can render the data form and initiate the request to the ACS. This data includes information which helps the ACS to risk assess. As soon as the ACS has gathered the browser/device it will let the 3DS Server know via the 3DS Method response.
Overview of fields in 3DS - difference between 2.1 and 2.2 protocol versions
Please look at the Excel file - Fields in 3DS - diff 21 vs 22.xlsx
EMV 3DS 2.3.1
How to get ready for EMV 3DS 2.3.1?
We are expecting card schemes to start sending EMV 3DS 2.3.1 card ranges supported from both ACS and DS, which will result in highestCommonSupportedVersion field in Versioning response to be 2.3.1. In order to be ready for this, since 2.3.1 AReq format for some of the fields is slightly different than its predecessors 2.2.0 and 2.1.0 (please find the differences in the 'Overview of fields in 3DS - difference between 2.2 and 2.3.1 protocol versions' section below), you need to adapt the logic when sending AReq. There are few things to be taken into consideration:
- If you are ready and want to process transactions with EMV 2.3.1 protocol version, then first check whether 2.3.1 is highestCommonSupportedVersion in the Versioning response. If it is, then format the AReq accordingly to 2.3.1 format and set preferredProtocolVersion to 2.3.1. If it is not, then fallback to the highestCommonSupportedVersion returned in Versioning response and format the AReq accordingly.
Are you certified with EMVCo 2.3.1 protocol?
Netcetera 3DS Server is certified by EMVCo for the 2.3.1 protocol version since March 2023. The LoA can be found here.
What are the steps for going live with 2.3.1 protocol version?
Successful processing of 2.3.1 transactions depends on all the 3DS component supporting that protocol version. Therefore, even though the Netcetera 3DS Server is EMVCo certified for the 2.3.1 protocol, there is a dependency to the Directory Server readiness to support such transactions, which can be individual for each scheme. When a Scheme (e.g. Visa, Mastercard) is ready to support 2.3.1 version and releases a guideline for integration, the certification process will be undergone, to additionally certify the Netcetera 3DS Server for that particular scheme. Once the 3DS Server is 2.3.1 certified with a scheme, it will be able to process 2.3.1 transactions for that specific scheme.
Can you explain the Decoupled Authentication Fallback in EMV 3DS 2.3.1?
Decoupled Authentication Fallback is reaction to failing authentications due to system errors with a fallback solution. A 3DS Requestor can indicate whether it supports the fallback scenario of a decoupled authentication for the case in which the ACS recognizes a connection error that would prevent the cardholder to perform the challenge. Once the ACS detects such an issue it can choose to proceed with a decoupled authentication, which will result in a challenge request to the cardholder at a later point in time, once network issues no longer exist.
What is SPC?
SPC (Secure Payment Confirmation) provides a method to perform a challenge using pre-established FIDO credentials when using a Browser. The SPC authentication can be initiated by the 3DS Requestor via an additional AReq/ARes message pair or by the ACS via a standard Browser Challenge Flow.
FIDO (Fast Identity Online) was born from the FIDO Alliance and has become a globally accepted authentication method. The major benefit for cardholders is the option to authenticate with security keys, facial recognition, their voice or fingerprint rather than using static or dynamic passwords. With EMV 3-D Secure 2.3.1, FIDO authentication is enabled within the 3DS browser flow, which means that cardholders can authenticate much faster and with less friction, while profiting from a very high security standard.
What improvements do the new 2.3.1 data fields bring?
The new data fields introduced with EMV 3DS 2.3.1 (e.g. seller info, recurring data, EMVCo token information) support issuers with identifying and approving transactions. Business models using recurring transactions have expanded over time and could no longer fit into the existent flow. However, with the new protocol version, businesses can indicate their use case more precisely by e.g. stating that the recurring date varies and the recurring amount is not fixed. Similarly, the travel industry was involved in defining of data elements for travel message extensions, such that these businesses can be more precise about what the cardholder authenticates. Furthermore, the response sent from ACS back to the merchant can now include information as to which exemption was applied, indicated by a new data field in the authentication response. This will help merchants better understand the decision-making process when applying for exemptions.
Overview of fields in 3DS - difference between 2.2 and 2.3.1 protocol versions
Please look at the Excel file - Fields in 3DS - diff 22 vs 23.xlsx
What to do if not ready for EMV 3DS 2.3.1?
If you are not ready or you do not plan to process transactions with EMV 2.3.1 protocol version, then you should send preferredProtocolVersion to version lower than 2.3.1 even if highestCommonSupportedVersion from the Versioning response is 2.3.1. If you send transaction with preferredProtocolVersion 2.3.1 (or latest) and AReq is not in 2.3.1 format, you will experience transactions failure. If you are sending latest as preferredProtocolVersion, then please adapt the logic on your side, since this option is now deprecated and will be removed after 6 months because of the differences between EMV 2.3.1 and 2.2.0 message format, and as previously mentioned, if AReq is in 2.2.0 format and preferredProtocolVersion is sent as latest, this will result in transactions failure if DS and ACS both supports the latest protocol version (2.3.1).
There are two possible adaptation in order to avoid having failed transactions:
- Always send 2.2.0 as a preferredProtocolVersion.
- Introduce a logic to choose preferredProtocolVersion out of highestCommonSupportedVersion returned in the Versioning response.
Merchants’ onboarding & configuration
As a PSP, can you walk me through the steps to get one of our merchants all set up on your platform?
As a prerequisite for processing 3DS 2.x transactions, the acquirer should enroll the merchants to Mastercard using their ISSM tool (other schemes such as Visa, Amex, Diners do not require prior merchant enrollment). The merchants and acquirers can be configured in the Admin UI for each scheme, or alternatively the merchant data can be sent directly in the payload (please refer to the example models for AReq (3DS 2.x) and PaReqCreationRequest (3DS 1.0)).
Can you walk me through the steps to get a Merchant onboarded with Mastercard?
For 3DS 1, acquirers can register and add merchants via the Mastercard form. The Qualtrics link should allow you to provide as many merchants as excel can handle. These are uploaded by Mastercard customer support team so they will likely parse the data on their end.
For 3DS 2, merchants’ enrollment is done via Mastercard ISSM tool. The Mastercard Merchant Enrollment API enables acquirers and their service providers to manage merchant participation in Mastercard Identity Check on EMV 3-D Secure (3DS 2.0). Acquirers and service providers can add or delete merchants directly in Mastercard ISSM by sending the enrollment data through API Interfaces, up to approximately 20,000. More details on the API can be found in Mastercard bulletin - AN 3264 - Identity Check Merchant Enrollment Application Program Interface.
The enrolment process from different vendors depends from the service provider MID structure. ISSM, the application tool for merchant enrolment does not allow duplicate MID/BIN entries. If the service providers all are using the same MID/BIN combo for the Areq then it only needs to be enrolled once.
Further information about the requestor data can be found here:
3DS Requestor data for MastercardCan you walk me through the steps to get a Merchant onboarded with Visa?
Visa provided information that they don’t require prior enrollment of merchants. The merchant information (id and name) should be part of self-assigned requestor information and should be sent during the Authentication Request message. We already have the service provider part of the requestor information. The attached 3DS requestor document provides more information on this topic.
Further information about the requestor data can be found here:
3DS Requestor data for VisaCan you walk me through the steps to get a Merchant onboarded with American Express (AMEX)?
Amex does not require enrollment of merchants anymore.
Further information about the requestor data can be found here:
3DS Requestor data for AMEXCan you walk me through the steps to get Merchant onboarded with Discover/Diners?
Onboarding of merchants with Discover/Diners is done by uploading an excel file with the merchant data (for both 3DS 1.0 and 2.0 enrolment). If the merchants are already enrolled in 1.0, Discover would need the information on the merchants that support 2.0 and vendors from which the transaction is processed (related with reference number).
Starting from October 2020 onwards, the merchant’s enrollment is not mandatory, and the merchant data can be provided directly in the request payload.
Similarly to Mastercard, if the 3DS Server is operated by two different service providers, there will be two different Operator IDs, which are associated with the merchant during the enrolment process.
Further information about the requestor data can be found here:
3DS Requestor data for Discover/DinersCan you walk me through the steps to get a Merchant onboarded with UnionPay?
UnionPay does not have a merchant enrollment process, since they let the acquirer or processor manage their merchants. However, necessary data elements (e.g. the Acquirer Merchant ID) should be sent in the transaction payload.
If different vendors are processing with the same merchant, they need to make sure that the authentication and authorization match, meaning that the Acquirer Merchant ID used in the authentication should be consistent with the one in the authorization.
Further information about the requestor data can be found here:
3DS Requestor data for UnionPayCan you walk me through the steps to get a Merchant onboarded with JCB?
Every enrollment of Acquirer/PSP requires a dedicated project towards JCB, where they perform a full authentication and authorization test plan. More information can be provided by JCB once the customer is identified.
If the acquirer merchant is not successfully registered with the scheme, the following error may appear:
Additional information about the requestor data can be found here:
3DS Requestor data for JCBUser Management
Can multiple people from one organization have access to the Admin UI?
Yes. Firstly, one person (full name/email) from the customer side is given Administrator rights to Netcetera Identity. Here, the Administrator can manage users i.e., add and remove users as well as do changes to the user roles, which controls their permissions. With access to Netcetera Identity, users can access the Admin UI on the customer-specific endpoint provided by Netcetera.
What is Netcetera Identity?
With Netcetera Identity, user management is in your hands. To enable this, a representative from an organization is given Administrator rights to Netcetera Identity for their organization. To login to Netcetera Identity, as well as to the Admin UI application, users need to authenticate themselves using 2 factors. The first factor is username and password; the second is the Futurae app.
What is Futurae?
Futurae is an Out-Of-Band authentication that will be used as second factor for the user's authentication when accessing the Admin UI. Eligible users can download the Futurae Mobile App from apple or play store. Find more information about Futurae app here.
Visa DAF program
What is Visa DAF?
The Digital Authentication Framework (DAF) outlines an approach for a consistent and verifiable set of transaction data that can increase issuer confidence and facilitate risk decisions that may lead to increased approval rates and lower fraud.
What is the responsibility of the Merchant?
Merchants participating in DAF using EMV 3DS will need to:
- Support EMV 3DS 2.1 or higher (is enabled by Netcetera 3DS Server)
- Support the DAF message extension in the authentication layer (is enabled by Netcetera 3DS Server)
- Support Field 34 in authorization (Optional)
- Support Visa Merchant ID
In Europe where PSD2 SCA applies to a transaction, a merchant/TR can only submit a transaction (domestic/intra-regional) under the DAF if:
- SCA has been completed either:
- Under the VisaDelegatedAuthenticationProgram(VDAP)
- Under an agreement in force with issuers for SCA delegation
- Or:
- The transaction is eligible for an Acquirer Strong Customer Authentication (SCA) exemption
For more information please contact your Visa representative.
What is the responsibility of the Acquirer?
Acquirers are responsible for registering their merchants for DAF EMV 3DS. To register for DAF EMV 3DS, a merchant’s acquirer must retrieve and confirm their Visa Merchant ID (VMID) with Visa. For details on program requirements or registration process please refer to the Digital Authentication Framework page of Visa Online (VOL). Issuers will be mandated to support Visa DAF starting from April 2023. Under the Digital Authentication Framework (DAF), issuers are liable for fraud on authenticated transactions that meet DAF requirements.
For more information please contact your Visa representative.
JSON Web Tokens (JWT) Authentication
NOT available for new customers
What are the best practices for securely storing the authentication token in a separate service?
When it comes to securely storing authentication tokens in a service, there are several options available:
- Environment Variables: Store the token as an environment variable within the service. This approach ensures that the token is not hard-coded in the codebase, reducing the risk of accidental exposure. Environment variables are typically accessed only by the service itself and are not visible to other processes running on the same machine.
- Secrets Manager: Utilize a secure secrets management service provided by your cloud provider, such as AWS Secrets Manager or Azure Key Vault. These services allow you to securely store and manage sensitive information like authentication tokens. You can retrieve the token programmatically when needed, and the service handles encryption and access controls.
- Parameter Store or Configuration Files: Store the token in a secure parameter store or configuration file specific to the service. These stores or files should have restricted access permissions and be encrypted if possible. The service can retrieve the token from the store or file during runtime.
- Cache Service (ex. Redis): Utilise a cache service for storing the token. The cache service can significantly enhance performance by providing a fast and efficient way to retrieve the token. It is crucial to consider security implications and implement proper measures to protect sensitive token information, such as encryption.
It's important to implement additional security measures when managing authentication tokens within a service:
- Restrict Access: Ensure that only authorized personnel or services can access the token storage mechanism or service configuration. Apply appropriate access controls and permissions to prevent unauthorized access.
- Encryption: If the token storage mechanism allows encryption, encrypt the stored token to provide an additional layer of protection.
- Audit Logs and Monitoring: Implement logging and monitoring capabilities to track access to the token storage, detect any suspicious activities, and respond to security incidents promptly.
- Token Rotation: Token rotation must be in place to regularly change the tokens used by the service. This helps mitigate the impact of compromised tokens and limits the window of opportunity for potential attackers.
By following these practices, you can enhance the security of token management within a service and reduce the risk of unauthorized access or exposure.
Can we use several multiple valid tokens with overlapping validity?
It is not recommended to have multiple valid tokens at a same time, but you could generate a new token close to the expiry date of the used token and have both tokens with overlapping validity.