Netcetera 3DS Server - Release Notes - Version


Published: 21.05.2021

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.

Upgrade Notes

  • Starting from this release by default transactions are not logged to a DB if it is configured to store 3DS Server configuration. Default behavior is to log them into a file only. With a new property set to file.db 3DS Server will continue logging transactions to a file and store them to a table in the DB as it was in previous releases. Find other possible values for this property on Configuration Properties page.
  • From this release on a new data model is used to store transaction logs in a DB. The old transaction logs are not automatically migrated to the new data model after the admin app is installed and is started up. It means they are not available in the transaction search results of the admin application. Only new transactions are visible there. To migrate old transactions run Transaction Logs Migration CLI Tool (3dss-cli-log-migration-tool/bin/ in the delivery package).
  • When using custom log4j2 configuration, the logging pattern of Transaction-Message-Appender must be adjusted as it's defined in default log4j2 configuration file.
  • In previous releases a fixed list of 3DS Server instances was configured in threedss.instance.endpoints property in the admin configuration properties. With Service Discovery introduced in this release 3DS Server instances register and unregister themselves in the Admin application upon their startup and shutdown respectively. In DB based configuration scenario add next properties to of 3DS Server to enable service discovery:
    • eureka.client.enabled=true
    • eureka.client.serviceUrl.defaultZone=http(s)://<admin-app-hostname>:<admin-app-port>/eureka
    • Note that in some complex network configurations eureka.instance.homePageUrl property should be configured as well. Find more details about service discovery configuration on Configuration Properties page.
    • Additionally add next configuration property to the of the Admin application to enable service discovery:
    • eureka.client.serviceUrl.defaultZone=http(s)://localhost:${server.port}/eureka
    • Note that the url is pointing to the same Admin application instance as it's running an embedded Eureka discovery server.
    • threedss.instance.endpoints can be removed from the
  • In Configuration Properties ds-client.cached-instance-expiry.days and mpi.ds-client.cached-instance-expiry-in-days are replaced by ds-client.cached-instance-expiry.seconds and mpi.ds-client.cached-instance-expiry-in-seconds respectively. Update the properties and their values (convert days to seconds) in the if custom values were previously configured.
  • Starting from this release, the 3DS Server is able to store completely overlapped card ranges received from different schemes. For this purpose, the directory server URL was added to the key in addition to start and end range values. In case EhCache is configured to store session and card ranges data the EhCache configuration should be updated with a new search attribute:
    • <searchAttribute name="directoryServerUrl" expression="key.getDirectoryServerUrl()"/>
    • in the searchable section of pResCardRangeData cache. Find an example of EhCache configuration file on EhCache Configuration page. Note such update should be done after all 3DS Server are down to avoid ehcache replication problems between 3DS Server instances of the new and an old version.
  • In case Redis is configured to store session and card ranges data, pres_card_range_data and pres_ds_data indexes should be removed before starting using this release. Note such update should be done after all 3DS Server instances are down to avoid incompatibility problems between 3DS Server instances of the new and an old version. In order to minimize the downtime the upgrade to the version should happen minimum one hour after the last preparation response was received so that the new preparation request (initiated from the instance) is not blocked by the Directory Server. An alternative is to start freshly the instances to a new, empty Redis instance and shut down the old 3DS Server instances and Redis one once the instances are up and running.


New Features

  • New API v2 for 3DS Versioning Method. For usage of new API version in the Versioning Method use v2 as a apiVersion path parameter in the Versioning endpoint. If no version is provided, default one is used. Example: /3ds/apiVersion/versioning where apiVersion can be v2. Please note that the default API version would be deprecated in 12 months.
  • After updating the configuration via the Admin, an information banner is shown to indicate that the 3DS Server is not yet informed about the change. After a successful Validate and Reload, the 3DS Server will be notified of all changes and the banner disappears.
  • Introduced a property which controls whether the organizationId header will be sent to the DS.
    • This property is by default switched off (false) and should be set to true when there are organization based card simulations configured in the NDM simulator. For more information please check NDM Configuration documentation.
  • Two properties are replaced with new to enable fine tuning of the connection pooling cache for outgoing connections.
    • ds-client.cached-instance-expiry.days is replaced with ds-client.cached-instance-expiry.seconds
    • mpi.ds-client.cached-instance-expiry-in-days is replaced with mpi.ds-client.cached-instance-expiry-in-seconds
    • The defaults of these properties was 1 (days), now it is replaced with 86400 (seconds) reflecting the same value.
  • Users with global admin role can switch between organizations in the Admin app. This will contribute to faster support and management of the organizations configured.
  • Introduced Service discovery to enable the Admin application dynamically discover 3DS Server instances
  • Elasticsearch as transactions log storage. 3DS Server and 3DS Server Admin application can be configured to use Elasticsearch to store and search transaction logs history. Using Elasticsearch as a log storage instead of SQL is advised in case of high number of incoming transactions. Find more information in the Elasticsearch documentation page.
  • New database model for storing of transaction logs. The 3DS Transaction CLI Tool is available for moving the transactions log data from the old database table to the new database tables.
  • Introduced a configuration option to disable PReq for a particular scheme.


  • Validation of cardholder name for non-ASCII characters introduced. Mastercard scheme excluded from this validation, since they support special characters in the cardholder name.
  • Allow storage of duplicated card ranges received from different schemes by adding Directory server URL as a key in addition to start and end range. This implicates that 3DS Server with version will not be able to join existing Ehcache or Redis clusters where the ranges are stored by a 3DS Server below version Additionally, if external EhCache configuration is used, please note that for the cache "pResCardRangeData", the "expression" for "directoryServerUrl" search attribute was changed.
  • Better resolving of card range data. When schemeId is present in the request, the resolved card range will be from the same scheme.
  • Showing a dialog before attempting to delete a Directory Server in the Admin UI.
  • Updated the 3DS Server Dashboard and Search Statistics in the Admin UI to only show transactions that are relevant to the active organization.
  • In a multi-tenant mode, if an organization is added, edited or deleted, the Admin application will now notify all 3DS Server instances asynchronously.
  • Faster loading time of Merchants Acquirers when having ~10000 Merchants.
  • Adding monitoring of "standard" outgoing HTTP calls from the 3ds server inside the Grafana dashboard in the "HTTP(OUT)" section.
  • The Timeout Configuration section inside the Schemes in the Admin UI will be shown only when it is configured.
  • Introducing new names for the metrics sent by the 3DS Server to Prometheus. Added new tags like orgName and dsUrl to the appropriate requests which will enable the classification of the requests per organization and scheme, respectively. Percentiles were added for some of the requests. For a detailed overview of the new and deprecated metrics, please see the Operation Manual, Monitoring section.
  • The 3dsctl script now takes node and application properties from custom path.
  • The set of values eligible for masking, that carry PII (Personally Identifiable Information), extended with fields cardExpiryDate and deliveryEmailAddress.
  • The set of values eligible for masking, that carry PII (Personally Identifiable Information), extended with fields cardExpiryDate and deliveryEmailAddress.
  • Error message improved when UPOP server not configured. API extended with error code UP-MISS.
  • New error code added DS-HTTP-404, when UPOP Server not reachable for UPOP inqury request.
  • Improved validation of the following fields in the 3DS Server configuration:
    • Scheme name - only alphanumerical characters, hyphen, space and underscore are allowed
    • Certificate store name - only alphanumerical characters, hyphen, space and underscore are allowed
    • 3DS Server reference number - only alphanumerical characters and underscore are allowed

Bug Fixes

  • 3DS Server Dashboard: Fixed session issues relating to the active organization and navigation bar. Refactored loading of pages on the Dashboard.
  • If a scheme is used in a preparation request that has no enabled endpoints, the application will no longer fail with a 500 error, but will return an error message ("No directory server endpoints configured or endpoints disabled.").
  • If any of the client certificate keys has password different than the password for a key-store, when uploading key-store from file, the application will no longer accept it.
  • AcquirerBin and MerchantAcquirers now can be stored with all empty fields inside the Admin UI.
  • Return error message when license is expired/not valid for 3DS 2 transactions
  • Web SDK will return successful Challenge to cardholders on MS Edge Browser
  • Redis health check for the AdminUI will only be shown when Redis is set as a session storage type.
  • Directory Servers with no active endpoints will not throw an error during PReq/PRes process logic.
  • Broken layout of documentation properties fixed.
  • Leading zeros in the purchase amount field from 3DS 1.0 PaReq are removed.
  • The Subject column from the Client and Trust certificates tables in the Admin UI is now divided into two columns. Subject column which now refers to the certificate Owner and Issuer column which refers to the certificate Issuer.
  • Adjusted validation of cardholder Email field in the AReq to be compliant with IETF RFC 5322.