There are two main configuration files for 3DSS application:
- YAML file which is the main config file (3dss-test-config.https.yaml);
- Keystore - the file which contains keys and certificates (3dss-test-keystore.jks)
The default configuration is displayed in Admin Console on the first installation. The files should be updated according to user's needs.
Before starting the application:
- 3dss-test-config.https.yaml to be configured;
- keys and certificates to be created and imported into JKS file;
YAML file contains all the necessary settings and it refers to the key aliases defined in JKS file.
The process of generating Key-Pairs, CSRs, importing of certificates to the keystore is described here .
In admin console it is possible:
- to update the active configuration;
- to change an inactive configuration;
- to create a new configuration by changing the active one;
- to delete configurations.
¶ Principles and the structure of YAML config file
NOTE: Changes in system settings require restarting of the application.
Changes in common and profile settings can be done without restarting of the application.
3DSS configuration file has a hierarchical structure.
Common section defines the parameters applicable to the whole system, but these parameters can be overridden on Profile level.
- system - system settings (port numbers, HTTP/HTTPS protocol versions, Server and client certificates for incoming requests, debug level);
- common - application settings common to all profiles;
- profiles - specific settings for different IPS (VISA, Mastercard), bank card ranges, or specific settings for different banks (in the case of multi-institution solutions - for example, when providing E-commerce/3-D Secure 2.0 services for different banks within one solution).
The detailed description of all parameters in YAML configuration is provided below:
system
Here the system settings are specified (ports, SSL settings, keys/certificates, the level of debug).
Changes in system settings require restarting of the application.
httpServer
ports
defaultPort
nonSslPortStrategy
E.g. nonSslPortStrategy: DISABLE
Possible values:
- NONE - no action
- REDIRECT - redirects non-SSL traffic that comes in on SSL port with Nginx.
- DISABLE - TODO: add description
port
E.g. port: '8044'
Defines the port used by the application.
TODO:to confirm Unless you have done it with Java options on the start of the application.
Possible values:
- 8080 - This default HTTP port is used for transferring web pages through insecure connection.
sslVerifyClient
E.g. sslVerifyClient: false
Enables verification of the client certificates.
If it's set to true then the Client certificate should be created, values should be added to sslServerKeyAlias and sslPort parameters.
Possible values:
sslPort
E.g. sslPort: '8443'
NOTE: Not available for the first configuration, can be added when a subsequent configuration is run.
Here you can specify the SSL port which is used by the application.
TODO:to confirmUnless you have done it with Java options on the start of application.
Possible values:
- 443 - This default HTTPS port is used for transferring web pages on a secure connection (encryption security)
NOTE: SSL does not have any specific port, but the HTTPS protocol, which uses SSL security, uses port 443. So, HTTPS indicates the existence of an SSL certificate in the URL. Data communication can be done with or without the existence of an SSL certificate.
But the port number indicates whether your connection is a secure one or not
sslServerKeyAlias
E.g. sslServerKeyAlias: '3dss-key-pair'
SSL Server Security Key Alias references to key name in key store (jks file).
NOTE: Not available for the first configuration, can be added when a subsequent configuration is run.
sslEnabledProtocols
E.g. sslEnabledProtocols: TLSv1.2,TLSv1.3
The versions of protocols used for communication
admin
NOTE: Not available for the first configuration, can be added when a subsequent configuration is run.
basicAuth
user
E.g. user: admin
Admin user name for logging into Admin console.
password
Admin user password for logging into Admin console.
enabled
Parameters that Enable authentication in Admin console with user and password.
Possible values:
port
E.g. port: '8044'
Here the port used by the application is defined
TODO:to confirm Unless you have done it with Java options on the start of the application.
Possible values:
- 8080 - This default HTTP port is used for transferring web pages through insecure connection.
sslVerifyClient
E.g. sslVerifyClient: false
Enables verification of the client certificates.
If it's set to true then the Client certificate should be created, values should be added to sslServerKeyAlias and sslPort parameters.
Possible values:
sslPort
E.g. sslPort: '8443'
NOTE: Not available for the first configuration, can be added when a subsequent configuration is run.
Here you can specify the SSL port which is used by the application.
TODO:to confirmUnless you have done it with Java options on the start of application.
Possible values:
- 443 - This default HTTPS port is used for transferring web pages on a secure connection (encryption security).
NOTE: SSL does not have any specific port, but the HTTPS protocol, which uses SSL security, uses port 443. So, HTTPS indicates the existence of an SSL certificate in the URL. Data communication can be done with or without the existence of an SSL certificate.
But the port number indicates whether your connection is a secure one or not.
sslServerKeyAlias
E.g. sslServerKeyAlias: '3dss-key-pair'
SSL Server Security Key Alias references to key name in key store (jks file).
NOTE: Not available for the first configuration, can be added when a subsequent configuration is run.
multipartResolver
Sets limits on config files that can be updated in one go.
requestSizeMax
E.g. requestSizeMax: 10000000
max=10000000 fileSizeMax
E.g. fileSizeMax: 10000000
max=10000000 debugMode
Sets debug mode for logs.
E.g. debugMode: true
NOTE: Logging levels serve different purposes. For detailed debugging information we use DEBUG, for general information INFO is used, WARN is used for potential issues, ERROR for errors that may impact functionality, and FATAL for critical errors that terminate applications.
Possible values:
Logging levels:
- INFO - logging level which tracks messages regarding routine application operations, such as when services start or stop running, resources being added, deleted, updated or modified in databases etc. Most system administrators monitor this log to make sure everything is functioning smoothly
- WARN - level messages are less frequent but still represent error conditions that prevent an application from functioning as it should. Although the application still functions, its existence should prompt developers or operations personnel to attend to it immediately
- ERROR - level messages are similar to INFO-level events, but their purpose is different - they represent situations which prevent an application from performing its usual operations normally. While work can continue normally despite this occurrence, its source should be investigated immediately
- FATAL - highest severity logging level and generally indicates messages that indicate something has broken in an application and require engineer intervention to continue functioning effectively. Therefore, you should use a log management service to alert you whenever these entries appear to prevent further data corruption and loss
- DEBUG - default logging level and should be used for debugging purposes during development. It includes detailed, granular information to aid in diagnosing issues in an application and third-party libraries used
temporaryInMemoryStorageThreadSize
Defines configuration load related settigns.
E.g. temporaryInMemoryStorageThreadSize: 1
temporaryInMemoryStorageTimeoutMs
Defines configuration load related settigns.
E.g. temporaryInMemoryStorageTimeoutMs: 600000
common
Defines the general settings that don't change depending on Network and IPS.
Changes in common settings don't require restarting of the application.
keyStore
NOTE: Should be used only one of the paratemers: fileKeyStore or databaseKeyStore.
fileKeyStore
type
E.g. type: 'JKS'
JKS, Java Key Store. You can find this file at sun.security.provider.JavaKeyStore. This keystore is Java specific, it usually has an extension of jks. This type of keystore can contain private keys and certificates, but it cannot be used to store secret keys. Since it's a Java specific keystore, so it cannot be used in other programming languages. The private keys stored in JKS cannot be extracted in Java
path
Defines JKS file location path on the server
password
Password of JKS file
enabled
E.g. enabled: false
Used to gather information about private keys and certificates from JKS file which is located on the server.
Used to store the server keys (both public and private) along with the signed certificate.
Possible values:
databaseKeyStore
enabled
E.g. enabled: true
Gathers information about private keys and certificates from Database.
Used to store the server keys (both public and private) along with the signed certificate.
Possible values:
referenceNumber
E.g. referenceNumber: 3DS_LOA_SER_DCOR_020200_00630
Defines the Identifier of D8 3DSS System (assigned by EMV). Gets updated after bi-anual re-certification.
NOTE: Reference Number can be override in profiles.overrides.
threeDSServerURL
E.g. threeDSServerURL: https://3dss:8443/rreq
Fully qualified URL of the 3DS Server where the DS will send the RReq message after the challenge has been completed.
Incorrect formatting will result in a failure to deliver the transaction results via the RReq message.
notificationURL
E.g. notificationURL: https://3dss-host:6444/api/cresponse
Fully qualified URL of the system that receives the CRes message or Error Message.
The CRes message is posted by the ACS through the Cardholder browser at the end of the challenge and recieving of the RRes message.
For example, for PGI to notify 3DSS on CRes PGI got from ACS (any port will work).
NOTE: "3dss-host" must be defined on PGI side (internal communication - with one bank).
threeDSMethodNotificationURL
E.g. threeDSMethodNotificationURL: https://3dss-host:6444/3dsmethod/handle-acs-notification
The URL that will receive the notification of 3DS Method completion from the ACS (external communication - from Any ACS).
It is sent in the initial request to the ACS from the 3DS Requestor executing the 3DS Method
threeDSMethodCollectURL
E.g. threeDSMethodCollectURL: https://3dss-host:6444/3dsmethod/collect
The URL that will collect Browser Information. Browser Information is obtained in the AReq message for ACS to determine the ability to support authentication on a particular Cardholder browser for each transaction.
The 3DS Server needs to populate the browser information for each transaction.
threeDSRequestorID
DS assigned 3DS Requestor identifier. Each DS will provide a unique ID to each 3DS Requestor on an individual basis. Requestor ID can be overridden in profiles.overrides.
Mastercard Rules and Recommendations:
- Requestor ID format must be: 'DS defined prefix for 3DS server_3DS server defined ID'.
- 3DS server defined ID for merchant connecting directly to the 3DS Server, could be Merchant's MID.
- 3DS server defined ID for scenario where merchants are connected through third parties, PSP, Gateways, Merchant Aggregators, and so forth. must be such that 3DS Server is able to identify the parties down to the merchant level.
NOTE:Special characters cannot be used within the requestor ID at this time. The only special character allowed is an underscore (_).Every 3DS Server will be assigned a Mastercard DS defined requestor ID prefix at time of onboarding. This prefix will be of length = 9 alphanumeric characters and will end with an underscore (_).
VISA Rules and Recommendations:
- ID Creator's Visa BID (8 characters)
threeDSRequestorName
DS assigned 3DS Requestor name. Each DS will provide a unique name to each 3DS Requestor on an individual basis. Requestor Name can be overridden in profiles.overrides.
Mastercard Rules and Recommendations:
- This name must be in the format: '3DS Server name_requesting entity'.
- The '3DS Server name' must match the name registered in the Mastercard DS at time of onboarding (3DS Server Company Name).
- The 'requesting entity' can be name of merchant connecting directly to the 3DS Server, or name of 3rd party/PSP/ Gateway/ Merchant Aggregator's (whichever is applicable).
NOTE: Special characters cannot be used within the requestor ID at this time. The only special character allowed is an underscore (_).
VISA Rules and Recommendations:
- Suggest that this should be the Merchant DBA (Doing Business As) name - this is not a hard requirement if this creates challenges.
threeDSRequestorURL
E.g. threeDSRequestorURL: https://samplebank.com
Fully qualified URL of 3DS Requestor website. This data element provides additional information to the receiving 3-D Secure system if a problem arises and should provide contact information.
Ideally it should be dynamic and passed from 3DS Requestor.
merchantCategoryCode
E.g. merchantCategoryCode: '5399'
DS-specific code describing the Merchant’s type of business, product or service (four-digit code).
merchantCountryCode
E.g. merchantCountryCode: '428'
Country Code of the Merchant. This value correlates to the Merchant Country Code (three-digit country code).
merchantName
E.g. merchantName: Example Merchant Name
Merchant name assigned by the Acquirer or Payment System
Mastercard Rules and Recommendations:
- This name must match the name registered in the Mastercard DS at time of enrollment. In use cases where the transaction is initiated by a different merchant, like in the case of a travel agent site managing booking for airlines or hotels, the name must follow the following format: 'Travel agent name_merchant (hotel or airline) name'
validation
Additional validation settings.
isNameAddressRestricted
E.g. isNameAddressRestricted: true
If isNameAddressRestricted is set to true, then requests will be validated to contain Billing and Shipping addresses.
remainFinalCResTimeout
E.g. remainFinalCResTimeout: 300000
Defines the Final CRes timeout in ms.
supportedMessageVersion
The protocol version supported by the application. Currently our product is certified for 2.2.0 only. 2.1.0 is no longer supported.
startVersion
E.g. startVersion: VERSION_2_2_0
The earliest (i.e. oldest) active protocol version that is supported.
endVersion
E.g. endVersion: VERSION_2_2_0
The most recent active protocol version that is supported.
profiles
This section defines DS-specific settings.
Changes in profiles settings don't require restarting of the application.
name
Defines the profile name, can be given any, for example named as IPS.
E.g. name: VISA
overrides
General settings applicable to all profiles are defined in Common section.
But here you can override settings from Common part and they will be specific for each PS.
threeDSServerOperatorID
E.g. threeDSServerOperatorID: '12345678'
Defines 3DS Server Operator ID which is provided by IPS.
Operator ID gets assigned to the specific client by IPS on the start of the project with IPS. For example, VISA uses Business ID (BID) as operator ID.
paymentSystem
E.g. paymentSystem: MASTERCARD
Defines the supported payment system.
acquirerBIN
E.g. acquirerBIN: '123456'
Defines the bank's acquirer BIN assigned by the DS.
NOTE: The following 4 parameters: threeDSRequestorID, threeDSRequestorName, threeDSRequestorURL, merchantName are set in Common part, but also can be overriden here.
threeDSRequestorID
DS assigned 3DS Requestor identifier. Each DS will provide a unique ID to each 3DS Requestor on an individual basis.
threeDSRequestorName
DS assigned 3DS Requestor name. Each DS will provide a unique name to each 3DS Requestor on an individual basis.
threeDSRequestorURL
E.g. threeDSRequestorURL: https://samplebank.com
Fully qualified URL of 3DS Requestor website. Ideally it should be dynamic and passed from 3DS Requestor.
merchantName
Merchant name assigned by the Acquirer or Payment System.
preparation
Defines Preparation (PReq) process related configs.
dsSender, dsClient, route define connection settings to DS.
dsSender
dsClient
route
name
E.g. name: VISA
Defines DS client name for preparation messages.
url
E.g. https://VisaSecureTestSuite-vsts.3dsecure.net/ds2
Fully qualified URL to the DS where the 3DS Server will send the PReq message.
connectionTimeout
E.g. connectionTimeout: 5000
Defines the Time (in ms) to wait for establishing a connection.
These time-out values are recommended ones (used during certification).
readTimeout
E.g. readTimeout: 10500
To ensure that 3-D Secure messages are handled across components in a timely manner, all components set read timeouts.
Read timeouts occur while waiting on a transaction response after the connection has been established and the message is sent to the recipient.
Connection timeouts occur while making the initial connection.
connectionPoolSize
E.g. connectionPoolSize: 1
TODO:to confirm The maximum number of connections to keep in the HTTP/1.1 keep alive cache. A value of 0 means that the cache is unbounded.
Connection pool is not applicable to Rest Client.
maxConnPerRoute
E.g. maxConnPerRoute: 5
Assigns maximum connection per route value.
maxConnTotal
E.g. maxConnTotal: 5
Assigns maximum total connection value.
connectionTimeToLiveTimeout
E.g. connectionTimeToLiveTimeout: 12000
Determines the maximum age of a connection (after which it will be closed), regardless of when the connection was used last. Normally, there is an "idle timeout" to cleanup connections, i.e. you or the other side will close a connection that is not used for a while.
sslEnabled
E.g. sslEnabled: true
Enables Server SSL authentication.
Possible values:
clientKeyAlias
E.g. clientKeyAlias: visa-3dss-client
Defines the Client key alias from the keystore for TLS.
disableSslCertValidation
E.g. disableSslCertValidation: true
Disable SSL certificate validation for SSL connection made after this call. This is installed as the default in the JVM for future calls. Returns the properly initialized SSLContext in case it is needed for something else (like Apache HttpClient libraries) but if you don't need it you can ignore it.
Must be enabled in PRODUCTION.
Possible values:
useSystemProperties
E.g. useSystemProperties: true
Use system properties when creating and configuring default implementations. For example, defines whether to use Apache HttpClientBuilder system properties (e.g. proxy settings).
Possible values:
enabledMessageLogging
TODO:add description
E.g. enabledMessageLogging: true
Possible values:
proxyHost
E.g. proxyHost: '10.30.10.54'
Proxy server that the HTTP/HTTPS protocol handler will use.
Should be defined if the forward proxy is used.
proxyPort
E.g. proxyPort: '8128'
Port that the HTTP/HTTPS protocol handler will use.
Should be defined if the forward proxy is used.
enabledDatabaseMessageLogging
E.g. enabledDatabaseMessageLogging: true
Defines whether to save messages in DB.
Possible values:
circuitBreakerEnabled
E.g. circuitBreakerEnabled: false
Parameter that enables using circuit breaker.
If enabled, it uses the default circuit-breaker impl, which will open the circuit after reaching a threshold of failure percentage.
If disabled, the circuit is permanently closed.
Possible values:
circuitBreakerOpenTimeout
E.g. circuitBreakerOpenTimeout: 5000
The timeout before a closed circuit is opened (in ms). When maxAttempts() failures are reached within this timeout, the circuit is opened automatically, preventing access to the downstream component.
circuitBreakerResetTimeout
E.g. circuitBreakerResetTimeout: 20000
The timeout before an open circuit is reset (in ms). If the circuit is opened longer than this timeout then it resets on the next call to give the downstream component a chance to respond again.
retryAttempts
E.g. retryAttempts: 2
How many times the system will retry to connect to service.
backOffTimeout
E.g. backOffTimeout: 1000
baseTempDirectory
Defines the location of temporary directory to save data in temp file ().
E.g. baseTempDirectory: ./tmp
bufferSize
E.g. bufferSize: 10000
Defines the size of the buffer file for logging events.
The optimal buffer size depends on several network environment factors including types of switches and systems, acknowledgment timing, error rates and network topology, memory size, and data transfer size.
calendar
Preparation scheduler (card range information must be refreshed 2 times a day)
Should be used only one type of intervalUnit: DAYS, HOURS or SECONDS
startAtHour
E.g. startAtHour: 23
startAtMinute
E.g. startAtMinute: 30
interval
E.g. interval: 10000
Possible values:
- 1 - for interval unit Days, one time per day
- 100 - for interval unit Hours, one time per day (360000s)
- 86400 - for interval unit Seconds (24h)
intervalUnit
E.g. intervalUnit: HOURS
Possible values:
allowDynamicProfileName
cleanUpInactiveRanges
Defines Card Range Data housekeeping settings.
TODO:add description and examples to the following parameters
amount
E.g. amount: 3
intervalUnit
E.g. intervalUnit: MONTHS
authentication
Defines Authentication (AReq) process related configuration parameters.
customDsSenders
CustomDsSenders are used to route operations directly to ACS, but it's not allowed by VISA and Mastercard.
Mastercard:
Requirement 140: All authentication messages for a Mastercard branded card including any Mastercard subsidiaries shall be submitted to the Mastercard DS when:
– the transaction is sent to Mastercard for authorization, or
– the card range is enrolled by the issuer or processor on IDC DS Payment Processors shall not bypass the DS and send requests directly to the ACS.
3DS Servers shall not bypass the DS and send requests directly to the ACS.
VISA:
2.12.7 Routing of Authentication Requests Through a Non-Visa Directory Server
- Issuers and acquirers must register the non-Visa Directory Server (DS) provider as a third-party agent and confirm the DS provider has completed the 3DS Security program.
threeDSServerURL
E.g. threeDSServerURL: https://3dss:8443/rreq
Overrides RReq URL for specific DS (ASC direct)
ranges
threeDSServerURL
E.g. threeDSServerURL: https://3dss:8443/rreq range
PAN Ranges to apply custom settings to.
start
E.g. start: 4123450000000000
Card range start value. end
E.g. start: 4123450000000000
Card range end value. dsSender
Defines main connection settings for Directory Server.
Settings are similar to those previously desribed in Preparation.
dsClient
route
name
E.g. name: VISA
DS client name, for example MASTERCARD or VISA.
healthCheckOff
E.g. healthCheckOff: true
url
E.g. url: https://VisaSecureTestSuite-vsts.3dsecure.net/ds2
Fully qualified URL of the DS where 3DS Server will send PReq message.
connectionTimeout
Default value: connectionTimeout: 5000
Time in ms to wait for establishing a connection with another member in the cluster.
readTimeout
Default value: readTimeout: 5000
To ensure that 3-D Secure messages are handled across components in a timely manner, all components set read timeouts.
Read timeouts occur while waiting on a transaction response after the connection has been established and the message is sent to the recipient. Connection timeouts occur while making the initial connection.connectionPoolSize
Default value: connectionPoolSize: 1
The maximum number of connections to keep in the HTTP/1.1 keep alive cache. A value of 0 means that the cache is unbounded. maxConnPerRoute
Default value: maxConnPerRoute: 5
Assigns maximum connection per route value.
maxConnTotal
Default value: maxConnTotal: 5
Assigns maximum total connection value.
connectionTimeToLiveTimeout
E.g. connectionTimeToLiveTimeout: 12000
Determines the maximum age of a connection (after which it will be closed), regardless of when the connection was last used. Normally, there is an "idle timeout" to cleanup connections, i.e. you or the other side will close a connection that is not used for a while. sslEnabled
E.g. sslEnabled: true
Enables SSL conection validation.
clientKeyAlias
E.g. clientKeyAlias: visa-3dss-client
Defines Client key alias. Key alias in the keystore for TLS.
disableSslCertValidation
E.g. disableSslCertValidation: true
Disables SSL certificate validation for SSL connection made after this call. This is installed as the default in the JVM for future calls. Returns the properly initialized SSLContext in case it is needed for something else (like Apache HttpClient libraries) but if you don't need it you can ignore it.
useSystemProperties
E.g. useSystemProperties: true
Uses system properties when creating and configuring default implementations.
enabledMessageLogging
E.g. enabledMessageLogging: true
proxyHost
E.g. proxyHost: '10.30.10.54'
Defines Proxy server that the HTTP/HTTPS protocol handler will use.
proxyPort
E.g. proxyPort: '8128'
Defines the port that the HTTP/HTTPS protocol handler will use.
enabledDatabaseMessageLogging
E.g. enabledDatabaseMessageLogging: true
circuitBreakerEnabled
E.g. circuitBreakerEnabled: false
Parameter that enables using circuit breaker.
If enabled, it uses the default circuit-breaker impl, which will open the circuit after reaching a threshold of failure percentage. If disabled, the circuit is permanently closed.
circuitBreakerOpenTimeout
Default value: circuitBreakerOpenTimeout: 5000
The timeout before a closed circuit is opened in ms. When maxAttempts() failures are reached within this timeout, the circuit is opened automatically, preventing access to the downstream component. circuitBreakerResetTimeout
Default value: circuitBreakerResetTimeout: 20000
The timeout before an open circuit is reset in milliseconds. If the circuit is open for longer than this timeout then it resets on the next call to give the downstream component a chance to respond again. retryAttempts
Default value: retryAttempts: 2
Defines how many times system will retry to connect to service.
backOffTimeout
Default value: backOffTimeout: 1000
baseTempDirectory
E.g. baseTempDirectory: ./tmp
Defines the location of a temporary directory for saving data in temp file ().bufferSize
Default value: bufferSize: 10000
Defines the size of the buffer file for logging events.
The optimal buffer size depends on several network environment factors including types of switches and systems, acknowledgment timing, error rates and network topology, memory size, and data transfer size. threeDSRequestorIDTemplate
E.g. threeDSRequestorIDTemplate: '123456*${acquirerMerchantID}'
threeDSRequestorNameTemplate
E.g.: threeDSRequestorNameTemplate: 'SampleBank*${merchantName}'
resolver
Resolvers are used to identify profile by card number.
Different resolvers can be used:
- database - lookup by card range data (acquired from DS)
- panRange - static ranges
- panPattern - Java Regex pattern
- masterCardByPan - for PANs starting with 5, 6 or 2
- visaByPan - for PANs starting with 4
panRange
range
start
E.g. start: 4123450000000000
Card range start value. end
E.g. start: 4123450000000000
Card range end value. order: 0
E.g. order: 0
database
order
E.g. order: 0