3DS 2.x NDM Simulator Configuration

NDM Simulator Configuration Properties

An application.properties file in the $NDM_SIMULATOR_HOME/conf directory is used to set configuration options for the Netcetera Demo Merchant Simulator.

The available configuration options and their default values are listed below.

Note: If you don't configure a value for one of the properties in your application.properties, the default value as shown below will be used.

Authentication Response and Results Request Configuration

The NDM Simulator allows external configuration of the simulated Authentication response and Results request per account number.

Possible types of Authentication Responses are listed below:

Possible types of Results Request are listed below:

If you are using a multi-tenant setup, the response type can be defined on organization level. In this case, a configuration consists of the organization ID, an underscore as delimiter and a pan.

Please note that if you choose to use configurations on organization level, the NDM Simulator would need to receive the specific organization ID in the request header. This is done by activating the ds.send.org.id=true flag in the 3DS Server application.properties. Furthermore, you will have to include the organization ID in the header of the result request that you send directly to the simulator (ACS). The header name is 3DS-Organization-ID.

The NDM Simulator tries to retrieve a configuration which matches the organization ID and pan. If no configuration is found, the NDM Simulator will look for global configurations with no organization ID but matching pan. If the card is not present at all in the configuration file, the default value is returned.

In order to configure the type of Authentication response and Results Request per account number, use the cardholder-numbers-simulated-message-types.properties configuration file in the $NDM_SIMULATOR_HOME/conf. An example on how to configure it is listed below:

There is also a possibility to configure specific message fields values per authentication response and results request type. The configurable message fields per authentication response type are listed below and (if configured) they must be provided in that specific order.

  • AUTHENTICATED_APPLICATION_FRICTIONLESS - authenticationValue,eci
  • NOT_AUTHENTICATED_APPLICATION_FRICTIONLESS - transStatusReason, cardholderInfo, eci
  • APPLICATION_FRICTIONLESS_MISSING_SDK_TRANS_ID - authenticationValue,eci
  • APPLICATION_CHALLENGE - transStatusReason, acsChallengeMandated, authenticationType
  • APPLICATION_CHALLENGE_OOB - transStatusReason, acsChallengeMandated, authenticationType
  • APPLICATION_CHALLENGE_SINGLE - transStatusReason, acsChallengeMandated, authenticationType
  • APPLICATION_CHALLENGE_MULTI - transStatusReason, acsChallengeMandated, authenticationType
  • APPLICATION_CHALLENGE_SDK_TRANS_ID_INVALID_FORMAT - transStatusReason, acsChallengeMandated, authenticationType
  • APPLICATION_DECOUPLED_CHALLENGE_VERSION_2_2_0 - transStatusReason, acsChallengeMandated
  • AUTHENTICATED_BROWSER_FRICTIONLESS - authenticationValue, eci
  • AUTHENTICATED_BROWSER_FRICTIONLESS_WITHOUT_BROAD_INFO - authenticationValue, eci
  • ATTEMPTED_BROWSER_FRICTIONLESS - authenticationValue, eci
  • NOT_AUTHENTICATED_BROWSER_FRICTIONLESS - transStatusReason, cardholderInfo, eci
  • UNAVAILABLE_BROWSER_FRICTIONLESS - transStatusReason, eci
  • REJECTED_BROWSER_FRICTIONLESS - transStatusReason, eci
  • BROWSER_FRICTIONLESS_MISSING_DS_TRANS_ID - authenticationValue, eci
  • BROWSER_CHALLENGE - transStatusReason, acsChallengeMandated, authenticationType
  • BROWSER_CHALLENGE_MISSING_ACS_URL - transStatusReason, acsChallengeMandated, authenticationType
  • BROWSER_DECOUPLED_CHALLENGE_VERSION_2_2_0 - transStatusReason, acsChallengeMandated
  • AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0 - authenticationValue, eci, whiteListStatus, whiteListStatusSource
  • THREE_RI - authenticationValue,eci
  • THREE_RI_CHALLENGE - transStatusReason, acsChallengeMandated, authenticationType
  • PROTOCOL_ERROR - errorComponent, errorCode, errorDescription, errorDetail
  • MERCHANT_WHITELIST_IN_CHALLENGE
    • When a card number with this simulation is used, the first response is BROWSER_CHALLENGE/APPLICATION_CHALLENGE. A checkbox will be shown in the challenge form for whitelisting a merchant. If this checkbox is checked every other transaction will be AUTHENTICATED_BROWSER_FRICTIONLESS/AUTHENTICATED_APPLICATION_FRICTIONLESS for a pre-configured period of time which is configured in the ehcache configuration for 'merchantWhitelistingData' cache'. Otherwise it will still be a BROWSER_CHALLENGE/APPLICATION_CHALLENGE.
  • INFORMATIONAL_VERSION_2_2_0 - authenticationValue, eci
  • VISA_DELEGATED_AUTHENTICATION_SUCCESS - authenticationValue
  • VISA_DELEGATED_AUTHENTICATION_DELEGATE_NOT_PARTICIPATING
  • VISA_DELEGATED_AUTHENTICATION_ISSUER_NOT_PARTICIPATING
  • VISA_DELEGATED_AUTHENTICATION_ISSUER_NOT_SUPPORTED
  • VISA_DELEGATED_AUTHENTICATION_TRANSACTION_EXCLUDED
  • VISA_DELEGATED_AUTHENTICATION_CHALLENGE
  • MASTERCARD_DELEGATED_AUTHENTICATION_SUCCESS - authenticationValue, eci
  • DELEGATED_AUTHENTICATION_NOT_SUPPORTED - authenticationValue, eci
  • DELEGATED_AUTHENTICATION_BINDING_ERROR - authenticationValue, eci
  • DELEGATED_AUTHENTICATION_AUTHENTICATE_ERROR - authenticationValue, eci

The configurable message fields per results request type are listed below and (if configured) they must be provided in that specific order.

  • AUTHENTICATED_TRANSACTION - authenticationValue, eci, transStatusReason,authenticationType
  • NOT_AUTHENTICATED_TRANSACTION - transStatusReason, authenticationType
  • AUTHENTICATED_TRANSACTION_MISSING_AUTHENTICATION_VALUE - eci, transStatusReason, authenticationType
  • PROTOCOL_ERROR - errorComponent, errorCode, errorDescription, errorDetail
  • AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0 - authenticationValue, eci, transStatusReason, whitelistStatus, whitelistStatusSource
  • NOT_AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0 - transStatusReason, whitelistStatus, whitelistStatusSource

The format requirements for each configurable message field are listed below:

  • authenticationValue - String, 28 characters
  • eci - String, 2 characters
  • transStatusReason - Values accepted:
    • 01 - CARD_AUTHENTICATION_FAILED
    • 02 - UNKNOWN_DEVICE
    • 03 - UNSUPPORTED_DEVICE
    • 04 - EXCEEDS_AUTHENTICATION_FREQUENCY_LIMIT
    • 05 - EXPIRED_CARD
    • 06 - INVALID_CARDNUMBER
    • 07 - INVALID_TRANSACTION
    • 08 - NO_CARD_RECORD
    • 09 - SECURITY_FAILURE
    • 10 - STOLEN_CARD
    • 11 - SUSPECTED_FRAUD
    • 12 - TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER
    • 13 - CARDHOLDER_NOT_ENROLLED_IN_SERVICE
    • 14 - TRANSACTION_TIMED_OUT_AT_THE_ACS
    • 15 - LOW_CONFIDENCE
    • 16 - MEDIUM_CONFIDENCE
    • 17 - HIGH_CONFIDENCE
    • 18 - VERY_HIGH_CONFIDENCE
    • 19 - EXCEEDS_ACS_MAXIMUM_CHALLENGES
    • 20 - NON_PAYMENT_TRANSACTION_NOT_SUPPORTED
    • 21 - THREE_RI_TRANSACTION_NOT_SUPPORTED
  • acsChallengeMandated - Values accepted:
    • Y - CHALLENGE_IS_MANDATED
    • N - CHALLENGE_IS_NOT_MANDATED
  • authenticationType - Values accepted:
    • 01 - STATIC
    • 02 - DYNAMIC
    • 03 - OUT_OF_BAND
  • whiteListStatus - Values accepted:
    • Y - WHITELISTED
    • N - NOT_WHITELISTED
    • E - NOT_ELIGIBLE_FOR_WHITELISTING
    • P - PENDING_CONFIRMATION
    • U - UNKNOWN
  • whiteListStatusSource - Values accepted:
    • 01 - THREE_DS_SERVER
    • 02 - DS
    • 03 - ACS
  • errorComponent - Values accepted:
    • C - THREE_DS_SDK
    • S - THREE_DS_SERVER
    • D - DIRECTORY_SERVER
    • A - ACCESS_CONTROL_SERVER
  • errorCode - Values accepted:
    • 101 - MESSAGE_RECEIVED_INVALID
    • 102 - MESSAGE_VERSION_NUMBER_NOT_SUPPORTED
    • 103 - SENT_MESSAGES_LIMIT_EXCEEDED
    • 201 - REQUIRED_ELEMENT_MISSING
    • 202 - CRITICAL_MESSAGE_EXTENSION_NOT_RECOGNIZED
    • 203 - FORMAT_ON_ONE_OR_MORE_ELEMENTS_INVALID_ACCORDING_SPECS
    • 204 - DUPLICATE_DATA_ELEMENT
    • 301 - TRANSACTION_ID_NOT_RECOGNIZED
    • 302 - DATA_DECRYPTION_FAILURE
    • 303 - ACCESS_DENIED_INVALID_ENDPOINT
    • 304 - ISO_CODE_NOT_VALID
    • 305 - TRANSACTION_DATA_NOT_VALID
    • 306 - MCC_NOT_VALID_FOR_PAYMENT_SYSTEM
    • 307 - SERIAL_NUMBER_NOT_VALID
    • 402 - TRANSACTION_TIMED_OUT
    • 403 - TRANSIENT_SYSTEM_FAILURE
    • 404 - PERMANENT_SYSTEM_FAILURE
    • 405 - SYSTEM_CONNECTION_FAILURE
  • errorDescription - String, maximum 2048 characters
  • errorDetail - String, maximum 2048 characters

In order to configure the authentication response and results request specific fields, the cardholder-numbers-simulated-message-types.properties configuration file in the $NDM_SIMULATOR_HOME/conf should be also used. If no configuration is provided for the message fields, default values will be used. An example configuration is listed below:

Card Range Data Configuration

The NDM Simulator allows external configuration of the Preparation response card ranges data used when simulating a Directory Server.

According to the end version an appropriate Preparation response card ranges data is being used for 2.3.1 protocol version or prior to that.

Each card range is configured in a separate row following the order of the message fields:

  • startRange - Start of the card range
  • endRange - End of the card range
  • actionIndicator - Indicates the action to take with the card range. Value accepted:
    • A = Add the card range
    • D = Delete the card range
    • M = Modify the card range (only for PReq messages with message version 2.2.0)
    • R = Randomly pick whether the action indicator to be A (Add)/D (Delete)
  • acsStartProtocolVersion - The earliest (i.e. oldest) active protocol version that is supported by the ACS
  • acsEndProtocolVersion - The most recent active protocol version that is supported for the ACS URL
  • dsStartProtocolVersion - The earliest (i.e. oldest) active protocol version that is supported by the DS
  • dsEndProtocolVersion - The most recent active protocol version that is supported for the DS
  • acsInfoIndicator - Indicates how actively and with which features a card range is participating in 3DS authentication.
    - 01 - Authentication available
- 02 - Attempts supported
- 03 - Decoupled authentication supported
- 04 - Whitelisting supported
  • threeDSMethodURL - The ACS URL that will be used by the 3DS Method.
  • schemeId - ID of the scheme on which this range belongs to. When schemeId is set then the card range belongs only to that scheme and is fetched from the fully-qualified-url-of-simulator/ds/valid-pres-configured-card-range-data endpoint having query parameter schemeId. When schemeId is not set then the card range is not scheme specific.
  • issuerCountryCode - Qualifies the Issuer country for the Ranges. (Since 2.3.1) Value accepted:
    • ISO 3166-1 numeric three-digit country code, other than the exceptions (901–999 Reserved by ISO to designate country names not otherwise defined).

The fields values are separated with comma and are defined in that specific order.

  • fully-qualified-url-of-simulator/ds/valid-pres-configured-card-range-data

An example configuration file on how to configure it exists in the $NDM_SIMULATOR_HOME/conf under the name simulated-card-range-data.properties and it is also listed below:

Challenge Flow Configuration

The NDM Simulator allows configuration of the Results Request sent when simulating an ACS for Challenge flow.

Each request is configured in a separate row following the order of the message fields:

  • challengeValue - The challenge input that the cardholder will insert to get the configured response. For Application Challenge OOB, this field should correspond to a specific cardholderAccountNumber.
  • transStatus - The status of the transaction
    • Y - Authentication / Account verification successful
    • N - Not authenticated / Account not verified; Transaction denied
    • U - Authentication / Account verification could not be performed; technical or other problem
    • C - In order to complete the authentication, a challenge is required
    • R - Authentication / Account verification Rejected. Issuer is rejecting authentication/verification and request that authorization not be attempted
    • A - Attempts processing performed; Not authenticated / verified, but a proof of attempt authentication / verification is provided
  • transStatusReason - Reason if the transaction failed. The values are defined in the EMVCo Specification. Any value defined in the specification will work. Examples:
    - 01 - Card authentication failed
- 02 - Unknown device
- 03 - Unsupported device
- 04 - Exceeds authentication frequency limit
- 05 - Expired card
- 06 - Invalid card number
- 07 - Invalid transaction
- 08 - No card record
- 09 - Security failure
- 10 - Stolen card
- 11 - Suspected fraud
  • eci - The eci value that will be sent in the RReq
  • authenticationValue - The authenticationValue that will be sent for a transaction.

The fields values are separated with comma, and are defined in that specific order.

In addition, the Results Request authenticationMethod parameter can also be configured for the different types. If configured, all Results Requests of the defined type will return the provided authenticationMethod. If not configured, the below default values will be returned: OTP: 02 SMS_OTP OOB: 09 OOB_OTHER SINGLE: 10 OTHER MULTI: 10 OTHER

Once the responses are configured, the cardholder can use the configured challenge values for simulating a RReq message.

An example configuration file on how to configure it exists in the $NDM_SIMULATOR_HOME/conf under the name simulated-challenge-responses.properties and it is also listed below:

Challenge Template

When initiating an authentication request to the NDM simulator, if the card is configured for Challenge flow, then the NDM simulator will set the acsURL field to be handled by the NDM Simulator Challenge handler.

The Netcetera Demo Merchant Simulator provides a pre-defined HTML template that is returned when initiating a Challenge Request to the simulated ACS Challenge handler. The OTP challenge screen and the template source are displayed below:

Challenge Template

Custom Challenge Template Configuration

The NDM Simulator can be also configured to provide a custom Challenge form. This can be configured via the ds-simulator-config.creq-form.template-location configuration property in the NDM Simulator Configuration Properties section.

In order for the NDM Simulator to properly handle challenge, the customized challenge template must contain the following placeholders:

  • A form with method POST whose action has value of "%otpValidationUrl$", like:

in order for the NDM Simulator to fill the OTP validation URL to a proper endpoint for validating the entered OTP.

  • An input field inside the form with value of "%threeDSSTransId$", like:

in order for the NDM Simulator to fill the 3DS Server Transaction ID and later on when validating the OTP to identify the transaction.

  • An input field inside the form with name "otp" (for the One Time Password), like:

in order for the NDM Simulator to handle the entered Challenge data.

  • An input field inside the form with value of %acctNumber$, like:

in order for the NDM Simulator to fill out the account number when whitelisting a merchant.

  • An input field inside the form of type checkbox with name "whitelistMerchant", like:

in order for the NDM Simulator to handle whitelisting of a merchant.

For handling challenge cancel, the custom challenge template should include additional submit button to the form with name 'challengeCancel', like:

Additionally, there is an option to include the following placeholders in the customized template, in order to provide details about the current transaction:

  • %maskedAcctNumber$ - the account number being masked
  • %merchantName$ - the merchant name
  • %purchaseAmount$ - the purchase amount
  • %purchaseCurrency$ - the purchase currency
  • %purchaseDate$ - the purchase date

The NDM Simulator will inject values into them retrieved from the current transaction.