Frequently Asked Questions (FAQ)

Netcetera environments and specifics

I have access to the demo/test environment. What can I use the demo/test environment for?
The demo/test environment is used for one free month of trial access to our 3DS Server SaaS solution. You’ll be automatically offboarded from the demo/test environment after the trial period of one month is over. Once you become a Netcetera customer you will get access to the cloud payment platform environments Preview and Production.
What is the difference between Preview and Production environments?
Preview is the environment which enables integration testing prior migrating to Production. The preview environment has an NDM Simulator installed and configured, containing a Directory Server as well as an ACS simulator with predefined schemes and testing card numbers test scenarios. The testing card numbers, accepted card ranges and multiple OTP challenges are provided to the customers by Netcetera.

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?
This is available on demand. It takes several days for the change to be done by Netcetera as this is a network change made on our Cloud Payment Platform, affecting the original setup, and needs to be carefully planned and scheduled.
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?

Visit compliance There you can see 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.

Integration

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.

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 merchantConfigurationId

Consequently, we highly recommend defining the values on your own. Every 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.

3DS Flow

What exemptions does the 3DS Server support?

Our 3DS Server is a EMVCo 3DS 2.2.0 protocol version certified product and 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 exemption

Please find in the “Exemptions guide” document additional information on the exemptions.

exemption-guide.pdfFile size: B
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 and 3DS 1.0. In the Preparation request initiated by the 3DS Server, the DS returns a list of card ranges that the DS handles and supported protocol versions for each card range. In the versioning request the 3DS Server matches if the cardholder account number is within the ranges returned from each configured directory server. If not, the application returns a message with an error. The versioning request can be used to check if the card is registered for 3DS 2.1.0. 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) and the ACS is unavailable, then the DS throws the error with transStatusreason = 82. The given issue needs to be checked by the ACS and the ACS needs to see that they can perform the given query and sending the proper response.

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, in case a card is co-branded and hence we will find it 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. Means, if you want to process trough domestic scheme, you must provide the schemeId.

Do you complete BIN matching on 3DS Server that confirms if a card is enrolled in 3DS 2?

With the versioning method the 3DS Server knows if a card range is enrolled in 3DS 2.0 or not. If the card range is enrolled, you should initiate the transaction with the 3DS Server. If it is not enrolled, then you should initiate the transaction as 3DS 1.0. More information regarding the method, you can find here: 3DS Versioning.

Please can you provide more details on 3DS 2 Flow?

The 3DS 2.0 flow is described here: 3DS 2.x API.

The threeDSMethodURL is gotten in the Versioning Response, which is the first response you are getting from the 3DS Server. After getting this threeDSMethodURL you should take the field threeDSMethodData from the threeDSMethodDataForm and initiate a request to the threeDSMethodURL via iframe.

This is an example of the field in the Versioning Response:

3DS Versioning.

After the method completion, you will be initiating an Authentication Request and you will get an Authentication Response form the server that in case of a challenge has a transStatus 'C'. Then you should take the base64EncodedChallengeRequest field from the Authentication Response and initiate a request to the acsURL also gotten in the Authentication Response via iframe. Here you can see authentication response samples.

At the end of the challenge, you should get a Result Response from the server to the URL you configured and a final CRes message from the ACS, approximately at the same time.

For more info on the implementation of browser based flow you can use the Netcetera 3DS Web SDK

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 receipt of the AReq message to help facilitate the transaction risk assessment.

For the versioning responses that contain a 3DS Method URL, the 3DS Requestor shall invoke the 3DS Method. The 3DS Method call shall 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 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 that you will open.

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 to include 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.

Fields in 3DS - difference between 2.1 and 2.2 3DS fields

Please look at the Excel file - Fields in 3DS - diff 21 vs 22.xlsx

fields-in-3ds-diff-21-vs-22.xlsxFile size: B

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?

Firstly, contact your acquirer - they should give you the merchant data. As a prerequisite for processing 3DS 2.x transactions, your acquirer should enroll the merchants to Mastercard using their ISSM tool (other schemes such as Visa, Amex, Diners do not require prior merchant enrollment). Secondly, configure the merchants and acquirers in the Admin UI for each scheme or alternatively send the merchant data 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 register and can 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 Mastercard.
Can 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.

3ds-requestor.pdfFile size: B

Further information about the requestor data can be found here:

3DS Requestor data for Visa.
Can 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 AMEX.
Can you walk me through the steps to get Merchant onboarded with Discovery/Diners?

The merchants are uploaded with the excel file. There is only one file for both 3DS 1.0 and 2.0 enrolment. If the merchants are already enrolled in 1.0, Discovery would need to receive info which of them will support also 2.0. They would like to know from which vendor the transaction is processed but that is related with reference number.

From October 2020 onwards, the merchant’s enrollment is not mandatory, but the merchant data can be provided directly in the requests.

It is similar as Mastercard, if the 3DS Server is operated by two different service providers there will be two different Operator IDs, which are actually associated with the merchant during the enrolment process.

Further information about the requestor data can be found here:

3DS Requestor data for Discovery/Diners.
Can you walk me through the steps to get a Merchant onboarded with UnionPay?

UnionPay confirmed that they don’t have a merchant enrollment process. They let the acquirer or processor manage their merchants. But necessary data elements (for example the Acquirer Merchant ID) should be sent in the transaction.

If different vendors are processing with the same merchant, they need to make sure the authentication and the authorization match, which means, the Acquirer Merchant ID used in the authentication should be consistent with that in the authorization.

Further information about the requestor data can be found here:

3DS Requestor data for UnionPay.
Can you walk me through the steps to get a Merchant onboarded with JCB?

Every enrollment of Acquirer/PSP required a dedicated project toward JCB, where they test full authentication and authorization transactions. More information can be provided by JCB once the customer is identified.

If the acquirer merchant is not successfully registered with the scheme, you can get the following error:

Additional information about the requestor data can be found here:

3DS Requestor data for JCB.

User 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 Auth. 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 Auth, users can access the Admin UI on the customer-specific endpoint provided by Netcetera.

What is Netcetera Auth?

With Netcetera Auth, user management is in your hands. To enable this, a representative from an organization is given Administrator rights to Netcetera Auth for their organization. To login to Netcetera Auth, 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.