3DS Server Installation Manual

System requirements

Disk and memory requirements are depending on the number of transactions that are processed per given time unit and the number of configured entities (Schemes, Acquirers and Merchants).

Operating system

The 3DS Server is recommended to be run on a Linux/Unix based operating system. E.g.

  • a GNU/Linux distribution (Example: CentOS)
  • a BSD derivative (Example: OpenBSD)
  • Mac OS X
  • Solaris

It's possible to run the 3DS Server on Windows. However, you will have to write your own scripts to control (i.e. start/stop) 3DS Server instances. Alternatively you can install Bash and additional tools (rm, dirname, tail, less) on Windows (e.g. via Cygwin) to run the 3dsctl script shipped with the 3DS Server.

Memory requirements

While a 3-D Secure transaction is ongoing, it consumes session memory. Every transaction uses around 152 b of session memory and the session data lifetime is up to 30 minutes. If we assume that the 3DS Server processes 100 transactions simultaneously at a given time, those ongoing transactions will consume session memory of around 15 Kb.

Additionally, the 3DS Server saves the preparation responses from the Directory Server in session memory in order to cache information about the Protocol Version(s) supported by available ACSs and the DS, and if one exists, about the corresponding 3DS Method URL. If we assume storing a preparation response containing only one card range data entry, then session memory of around 1 Kb will be used. For a preparation response containing 10 000 card range data entries, session memory of 3204 Kb will be used.

Prerequisites

Software Requirements

To run the 3DS Server application the following software installations are needed:

  • Java Development Kit (JDK) 11
  • Bash shell (to run the scripts)
  • Unix utilities used in the scripts: cat, curl, grep, less, sed, tail, tr
  • (Optional; for a load balancer setup) A load balancer, e.g. Apache 2.4 (or higher)

Valid 3DS Server License

3DS Server requires a valid license in order to be used.

You can request your license by e-mail on the following address: mpi@netcetera.com.

Upgrade guide

Each 3DS Server release package is structured as defined in the Installation guide. When unpacking the 3DS Server package, it will create the described folder structure, except the node-NODE-ID directory. Depending on the archiving tool used to unpack the 3DS Server package, it is possible that the previously defined configurations will be overwritten.

In order to preserve the configuration files from the previous 3DS Server installation we recommend:

  • back up the previous configuration files before installing the new 3DS Server, or
  • use a separate configuration directory (see Configuration)

Installation guide

Unzip the 3DS Server package (nca-3dss-package-<version>.zip) to a directory of your choice.

This will create the following directory structure rooted at $THREEDS_HOME:

Directory structure
-------------------
 
$THREEDS_HOME/                                                  <-- The unzipped directory contained in the nca-3dss-package zip file (nca-3dss-package-<version>).
  |
  +-- docs/                                                     <-- 3DS Server documentation
  |     |     |
  |     +-- ...
  |     |     |
  +-- 3ds-server/
  |     +-- bin/
  |     |     |
  |     |     +-- 3dsctl.sh                                     <-- Script to start/stop 3DS Server nodes.
  |     |     |
  |     |     +-- 3dstool.sh                                     <-- Script to generate encrypted content from plain-text input
  |     |
  |     +-- conf/                                               <-- Sample (default) configurations used by the 3dsctl script and the 3DS Server application.
  |     |     |
  |     |     +-- application.properties                        <-- Sample configuration settings
  |     |     |
  |     |     +-- ehcache.xml                                   <-- Sample session Ehcache configuration (without replication)
  |     |     |
  |     |     +-- 3dss-configuration.xml                        <-- Template 3DS Server 3-D Secure entities configuration
  |     |
  |     |
  |     +-- lib/
  |     |     |
  |     |     +-- nca-3ds-server.jar                            <-- The 3DS Server jar file.
  |     |     |
  |     |     +-- nca-3ds-web-sdk.js                            <-- The Netcetera 3DS Web SDK JavaScript that contains 3DS Method and Challenge Request helpers
  |     |     |
  |     |     +-- json-schema/                                  <-- JSON Schema files to help generate initial POJO classes for 3DS Server APIs
  |     |
  |     +-- node-<node-ID>/                                     <-- Extract directory created by starting an 3DS Server node via the 3dsctl script.
  |     |     |
  |     |     +-- logs/
  |     |     |
  |     |     +-- out/                                          <-- Directory where the Server startup logs are written to.
  |     |     |     |
  |     |           +-- catalina.out
  |     |     |
  |     |     +-- pid/                                          <-- Directory where the 3dsctl script stores PIDs of running 3DS Server nodes.
  |     |     |     |
  |     |     |     +-- node.pid
  |     |
  |     +-- xsd/                                                <-- XML schemas used by the 3DS Server for your reference.
  |           |
  |           +-- ...
  +-- 3dss-admin-ui/
  |     |
  |     +-- bin/
  |     |     |
  |     |     +-- 3dssadminuictl.sh                             <-- Script to start/stop 3DS Server Admin UI.
  |     |
  |     +-- lib/
  |     |     |
  |     |     +-- nca-3dss-admin-ui.jar                         <-- The 3DS Server Admin UI jar file.
 
-------------------

Configuration

Create a directory $THREEDS_CONFIG_HOME where you can store the 3DS Server configuration (e.g. $HOME/.threeDSServer).

Copy the sample configuration files from $THREEDS_HOME/3ds-server/conf to $THREEDS_CONFIG_HOME.

Configure 3-D Secure entities

The 3DS Server entities (Schemes, Acquirers, Merchants, etc.) can be configured using XML or Database configuration.

XML configuration

Configure your 3-D Secure entities in $THREEDS_CONFIG_HOME/3dss-configuration.xml. Add Schemes, Acquirers and Merchants. Refer to the 3DS Server XML Configuration documentation for details about the configuration.

Database configuration

3DS Server supported database are:

  • PostgreSQL 9.5 or higher.
  • MySQL 8.0.13 or higher.
  • Microsoft SQL Server 2016 or higher.
  • Oracle 12.0c or higher.

When the 3DS Server configuration is persisted in database the 3DS Server provides an Admin Web application for configuring the 3-D Secure entities. Refer to 3DS Server Admin Installation Manual and 3DS Server Admin Web Application documentation for details about the configuration. When using database configuration, it is recommended that the 3DS Server Admin is started and the 3DS Server configuration is updated before starting the 3DS Server instance.

Configure Tomcat

See Tomcat Configuration.

Configure Ehcache

Ehcache cache is used for storing the following cache and session data:

  • Preparation Response data: The Protocol Version(s) supported by available ACSs and the DS, and if exists, the 3DS Method URL.
  • 3DS Method completion data (per transaction ID)

See Ehcache Configuration.

Configure 3DS Server license

Once you have obtained the 3DS Server license file (3dss.lic), put it in the $THREEDS_CONFIG_HOME where you store the 3DS Server configuration.

For more details about the license file configuration, check the configuration of license.resource-location property in 3DS Server Configuration Properties documentation.

Additional configuration settings

Additional configuration properties can be set via $THREEDS_CONFIG_HOME/application.properties.

For details on the available configuration properties consult the 3DS Server Configuration Properties documentation.

Startup the 3DS Server

You can start the 3DS Server using the 3dsctl script:

$ $THREEDS_HOME/3ds-server/bin/3dsctl.sh -c $THREEDS_CONFIG_HOME start

Optionally, java parameters can be passed.

Similarly you can stop the 3DS Server using the following command:

$ $THREEDS_HOME/3ds-server/bin/3dsctl.sh stop

Testing the installation

To checks whether the 3DS Server application is up and running, navigate to http(s)://<host>:<port>/admin/dashboard. If everything went fine, you should see the 3DS Server Dashboard. Otherwise check the log files under $THREEDS_HOME/3ds-server/node-<NODE-ID>/logs for errors.