Netcetera 3DS Server - Release Notes - Version


Published: 06.06.2023

Version is a major release of the Netcetera 3DS Server.

For documentation about this release please refer to the documentation site.


This version is NOT backwards compatible with previous versions of the Netcetera 3DS Server.

Important notification

  • Netcetera 3DS Server is certified for EMV 3DS v2.3.1 protocol version and has received a new reference number from the EMVCo (3DS_LOA_SER_NEAG_020301_00682), supporting 2.1.0, 2.2.0 and 2.3.1 transactions. Currently, this value is set as default in the XML configuration and it should be overwritten if that is not the case already.
  • The new data field "acquirerCountryCode" is required for all 2.3.1 transactions. The already existing acquirer configurations should be timely updated to have this value set in order to successfully process 2.3.1 transactions.
  • Preferred protocol version data field (preferredProtocolVersion) is strongly recommended to be used. By AN 7264 - New Data Integrity Monitoring Program Edits for Identity Check Version Control from Mastercard, for all Mastercard card ranges, EMV 3DS 2.2 protocol version along with 2.2 message structure version, must be used in scenarios where the ACS (Issuing (BIN) range) supports 2.2 or higher protocol version. In line with the above change by Mastercard and the process of compliance with the scheme’s support strategy, for version EMV 3DS 2.1, following changes are planned to be implemented in the next major release version in 6 months from now:
    • In case the preferred protocol version is not used, the transaction will be processed with the highest supported ACS and DS protocol version.
    • In case the highest supported protocol version is different from the message structure version, the transaction will result in error.
    • Field enforcePreferredProtocolVersion will be no longer used.

Upgrade Notes

If the 3DS Server operates on multiple instances, the Installation of the version of Netcetera 3DS Server on the instance responsible for handling "Preparation Requests" is strongly recommended to be done as last step in the installation process.

This release introduces new configuration properties for the Netcetera 3DS Server application. For detailed documentation please refer to the 3DS Server Configuration Properties.

These are the included changes:

Added 3DS Server configuration properties:

Renamed 3DS Server configuration properties (old name -> new name): -> -> -> -> -> ->


New Features

Added support of EMV 3DS 2.3.1 protocol version. Major changes and new features are described below:

  • New Message pair (OReq/ORes) is outside of 3DS flow for additional communication between Directory Server (DS) and 3DS Server. Operation Messages can be used to convey operational information about the overall EMV 3DS program system health and management. Examples: reporting on turnaround times and performance, detecting and flagging rogue players in the ecosystem, DS communicating key exchange/certificate updates/reminders, exchanging information on compromised devices.
    • OReq message sequence is created to communicate operational information serving as an alert, a reminder, report, or call to action.
    • ORes message acknowledges receipt of the OReq message sequence. The message is created by the recipient of the OReq message and sent to the source of the OReq message.
  • Preparation flow changes:
    • Downloading of Card Range data file from the DS enables the 3DS Server to receive the card range data in a compiled .zip file which can be downloaded given that the DS Supports this option. If a DS does not support this feature, it will return the full cache via standard PRes.
    • Handling of compressed request and response gzip body within PReq/PRes. The 3DS Sever shall request the Card Range Data under a compressed format by adding "Accept-Encoding: gzip" to the HTTP request. The DS can decide to return the PRes within that compressed format OR use an uncompressed response body.
    • The DS provides a list of URLs (optionally, with the country code) in case there are preferred DS URLs for certain countries. Netcetera 3DS Server has implemented the resolution of DS endpoints from the "dsUrlList" in order to send the transaction to the optimal URL.
    • For a 2.3.1 preparation response, in addition to the existing validations, the 3DS Server validates the accuracy of the action indicators for the card ranges (ADD, MODIFY, DELETE) and does overlapping ranges check. In case when there is an issue with the action indicator (e.g. action indicator DELETE is received for a non-existent range), or there are overlapping ranges received by the Directory Server, the 3DS Server will discard the information received in the preparation response and will send a protocol error to the Directory Server.
  • Enhanced exchange of data between merchant and issuer with new data fields in the 3DS messages: AReq, ARes, CReq, CRes, RReq. Detailed overview of the new data fields compared to the EMV 3DS 2.2 protocol version per message pair can be found in the FAQ section. Examples of enhanced data exchange:
    • "transChallengeExemption" field is a new data filed in the Authentication response from ACS on which exemption was applied. This will help merchants to improve their exemption logic.
    • Additional recurring transaction data and EMV Payment Token data, which help issuers to better identify the transaction and can simplify the authentication experience for future purchases.
    • New data element "sellerInfo" in the AReq where merchants submit transaction details on behalf of another entity to support use cases when individual sellers in a marketplace.
    • New "multiTransaction" data field to support the cardholder invoking multiple transactions or merchants.
    • "deviceBindingStatus", "deviceBindingStatusSource" are new data fields to enable the consumer to be remembered on their device and reduce the need for an authentication challenge.
    • "trustList" data fields are replaced with "whitelist" data fields.
    • "acquirerCountryCode" is a new required field in the AReq, which can be sent in the payload or set in the Acquirer configuration. This information indicates where the acquirer is located and whether a "one-leg-out" transaction can be performed (if either the issuer or the acquirer is not located within the EEA). In such cases, the SCA is not mandatory.
    • More granular 3DS Requestor Challenge Indicator, enabling issuers to understand why SCA is needed. New values also include the exemptions for LVP (Low Value Payment) and SCP (Secure Corporate Payment).
  • Secure Payment Confirmation (SPC) - in collaboration with WC3 and FIDO Alliance, a new authentication method is supported. SPC 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 extra AReq/ARes message pair or by the ACS via a standard Browser Challenge Flow. It is designed to scale authentication across merchants, to be used within a wide range of authentication protocols, and to produce cryptographic evidence that the user has confirmed transaction details. Please see examples here. The Netcetera 3DS Web SDK is extended with a new method that initiates SPC authenticаtion. For more information check this page.
  • Decoupled Authentication fallback is a react to failing authentications due to system errors with a fallback solution. 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 when no network issues exist. Please see examples here.
  • HTTP headers (X-Request-ID, X-Response-ID) containing additional transaction ID information are introduced to support logging and monitoring of 3DS messages.


  • Faster startup of 3DS Server when database is used as a configuration storage achieved by removing of validation of 3DS Server Configuration on startup and parallelization of tasks in case multiple organisations are present.
  • Created a page with frequently asked questions and answers. For more information go to this page.
  • Removed the following unused columns from the following tables:
    • threedss_configuration_id from table logged_transaction
    • revision_number from tables pres_ds_data and pres_card_range_data
  • Introduced a circuit breaker when posting the Results response to the Requestor environment. This new feature will help improve the stability and reliability of our system by preventing cascading failures that can occur when the external service experiences issues. It is fully configurable within the application properties and if you want to use it, you will need to enable it, because by default it is disabled. Please see the threedsserver.results-response.circuit-breaker.* configuration properties for the Netcetera 3DS Server application.