NDM Simulator Configuration

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:

7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
public enum AuthenticationResponseTypeEnum {
 
  /**
   * Authenticated application frictionless authentication response.
   */
  AUTHENTICATED_APPLICATION_FRICTIONLESS,
  /**
   * Not authenticated application frictionless authentication response.
   */
  NOT_AUTHENTICATED_APPLICATION_FRICTIONLESS,
  /**
   * Invalid application frictionless authentication response with missing sdkTransId.
   */
  APPLICATION_FRICTIONLESS_MISSING_SDK_TRANS_ID,
  /**
   * Application challenge authentication response.
   */
  APPLICATION_CHALLENGE,
  /**
   * Invalid application challenge authentication response with sdkTransId having invalid format.
   */
  APPLICATION_CHALLENGE_SDK_TRANS_ID_INVALID_FORMAT,
  /**
   * Authenticated browser frictionless authentication response.
   */
  AUTHENTICATED_BROWSER_FRICTIONLESS,
  /**
   * Not authenticated browser frictionless authentication response.
   */
  NOT_AUTHENTICATED_BROWSER_FRICTIONLESS,
  /**
   * Invalid browser frictionless authentication response with missing dsTransId.
   */
  BROWSER_FRICTIONLESS_MISSING_DS_TRANS_ID,
  /**
   * Browser challenge authentication response.
   */
  BROWSER_CHALLENGE,
  /**
   * Invalid browser challenge authentication response with missing acsURL.
   */
  BROWSER_CHALLENGE_MISSING_ACS_URL,
  /**
   * 3RI authentication response.
   */
  THREE_RI,
  /**
   * Protocol error.
   */
  PROTOCOL_ERROR,
  /**
   * Browser using Decoupled Authentication.
   */
  BROWSER_DECOUPLED_CHALLENGE_VERSION_2_2_0,
 
  /**
   * Authenticated, Merchant whitelisted.
   */
  AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0
}

Possible types of Results Request are listed below:

7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
public enum ResultsRequestTypeEnum {
 
  /**
   * Results request indicating authenticated transaction.
   */
  AUTHENTICATED_TRANSACTION,
  /**
   * Invalid results request indicating authenticated transaction.
   */
  AUTHENTICATED_TRANSACTION_MISSING_AUTHENTICATION_VALUE,
  /**
   * Authenticated transaction with possibility to configure merchant whitelist.
   */
  AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0,
  /**
   * Not authenticated transaction with possibility to configure merchant whitelist.
   */
  NOT_AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0,
  /**
   * Results request indicating not authenticated transaction.
   */
  NOT_AUTHENTICATED_TRANSACTION,
  /**
   * Protocol error.
   */
  PROTOCOL_ERROR
 
}

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000000.aRes=AUTHENTICATED_APPLICATION_FRICTIONLESS
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000001.aRes=NOT_AUTHENTICATED_APPLICATION_FRICTIONLESS
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000002.aRes=APPLICATION_FRICTIONLESS_MISSING_SDK_TRANS_ID
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000003.aRes=APPLICATION_CHALLENGE
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000003.rReq=AUTHENTICATED_TRANSACTION
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000004.aRes=APPLICATION_CHALLENGE_SDK_TRANS_ID_INVALID_FORMAT
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000005.aRes=AUTHENTICATED_BROWSER_FRICTIONLESS
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000006.aRes=NOT_AUTHENTICATED_BROWSER_FRICTIONLESS
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000007.aRes=BROWSER_FRICTIONLESS_MISSING_DS_TRANS_ID
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000008.aRes=BROWSER_CHALLENGE
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000008.rReq=NOT_AUTHENTICATED_TRANSACTION
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000009.aRes=BROWSER_CHALLENGE_MISSING_ACS_URL
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000010.aRes=THREE_RI
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000011.aRes=PROTOCOL_ERROR
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4916486411972975.aRes=BROWSER_CHALLENGE
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4916486411972975.rReq=AUTHENTICATED_TRANSACTION
threedsdemo.cardholderNumbersSimulatedMessageTypes.num7654310438720050.aRes=APPLICATION_CHALLENGE
threedsdemo.cardholderNumbersSimulatedMessageTypes.num7654310438720050.rReq=NOT_AUTHENTICATED_TRANSACTION
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000012.aRes=BROWSER_CHALLENGE
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000012.rReq=AUTHENTICATED_TRANSACTION_MISSING_AUTHENTICATION_VALUE
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000013.aRes=APPLICATION_CHALLENGE
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000013.rReq=PROTOCOL_ERROR
threedsdemo.cardholderNumbersSimulatedMessageTypes.num6000009000000001.aRes=BROWSER_DECOUPLED_CHALLENGE_VERSION_2_2_0
threedsdemo.cardholderNumbersSimulatedMessageTypes.num6000009000000001.rReq=NOT_AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0
threedsdemo.cardholderNumbersSimulatedMessageTypes.num6000009000000002.aRes=AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000009000000003.aRes=BROWSER_CHALLENGE
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000009000000003.rReq=AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0,MTIzNDU2Nzg5MDA5ODc2NTQzMjE=,02,17,Y,80

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
  • APPLICATION_FRICTIONLESS_MISSING_SDK_TRANS_ID - authenticationValue,eci
  • APPLICATION_CHALLENGE - transStatusReason, acsChallengeMandated, authenticationType
  • APPLICATION_CHALLENGE_SDK_TRANS_ID_INVALID_FORMAT - transStatusReason, acsChallengeMandated, authenticationType
  • AUTHENTICATED_BROWSER_FRICTIONLESS - authenticationValue, eci
  • NOT_AUTHENTICATED_BROWSER_FRICTIONLESS - transStatusReason
  • 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, authenticationType
  • AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0 - authenticationValue, eci, whiteListStatus, whiteListStatusSource
  • THREE_RI - authenticationValue,eci
  • PROTOCOL_ERROR - errorComponent, errorCode, errorDescription, errorDetail

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000000.aRes=AUTHENTICATED_APPLICATION_FRICTIONLESS,MTIzNDU2Nzg5MDA5ODc2NTQkokW=,09
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000001.aRes=NOT_AUTHENTICATED_APPLICATION_FRICTIONLESS,01
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000002.aRes=APPLICATION_FRICTIONLESS_MISSING_SDK_TRANS_ID,MTIzNDU2Nzg5MDA5ODc2NTQkokW=,09
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000003.aRes=APPLICATION_CHALLENGE,01,Y,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000003.rReq=AUTHENTICATED_TRANSACTION,MTIzNDU2Nzg5MDA5ODc2NTQzMjE=,02,18,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000004.aRes=APPLICATION_CHALLENGE_SDK_TRANS_ID_INVALID_FORMAT,01,Y,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000005.aRes=AUTHENTICATED_BROWSER_FRICTIONLESS,MTIzNDU2Nzg5MDA5ODc2NTQkokW=,09
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000006.aRes=NOT_AUTHENTICATED_BROWSER_FRICTIONLESS,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000007.aRes=BROWSER_FRICTIONLESS_MISSING_DS_TRANS_ID,MTIzNDU2Nzg5MDA5ODc2NTQkokW=,09
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000008.aRes=BROWSER_CHALLENGE,01,Y,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000008.rReq=NOT_AUTHENTICATED_TRANSACTION,07,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000009.aRes=BROWSER_CHALLENGE_MISSING_ACS_URL,01,Y,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000010.aRes=THREE_RI,MTIzNDU2Nzg5MDA5ODc2NTQkokW=,09
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000011.aRes=PROTOCOL_ERROR,D,101,error description,error detail
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000012.aRes=BROWSER_CHALLENGE,01,Y,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000012.rReq=AUTHENTICATED_TRANSACTION_MISSING_AUTHENTICATION_VALUE,02,07,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000013.aRes=APPLICATION_CHALLENGE,01,Y,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000013.rReq=PROTOCOL_ERROR,A,201,error description,error detail
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000014.aRes=BROWSER_DECOUPLED_CHALLENGE_VERSION_2_2_0,01,Y,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000014.rReq=AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0,MTIzNDU2Nzg5MDA5ODc2NTQkokW=,09,18,Y,03
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000015.aRes=AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0,MTIzNDU2Nzg5MDA5ODc2NTQkokW=,09,Y,01
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000016.aRes=BROWSER_DECOUPLED_CHALLENGE_VERSION_2_2_0,01,Y,02
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000016.rReq=NOT_AUTHENTICATED_MERCHANT_WHITELIST_VERSION_2_2_0,18,N,03

Card range data configuration

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

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

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

Once the card ranges are configured a preparation response including them will be returned on the following endpoint:

  • 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:

1
threedsdemo.simulated-card-range-data.ranges[0]=4000000000000000,4000009999999999,M,2.1.0,2.2.0,2.1.0,2.2.0,01|02|03|04

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:

  • otpValue - The OTP input that the cardholder will insert to get the configured response
  • 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.

Once the responses are configured, the cardholder can use the configured OTP 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-otp-responses.properties and it is also listed below:

1
2
3
4
5
6
#otpValue,transStatus,transStatusReason,eci,authenticationValue
threedsdemo.simulated-otp-responses.responses[0]=1234,Y,,01,JAmi21makAifmwqo2120cjq1AAA=
threedsdemo.simulated-otp-responses.responses[1]=1111,N,01,01,
threedsdemo.simulated-otp-responses.responses[2]=2222,R,01,01,
threedsdemo.simulated-otp-responses.responses[3]=3333,U,01,01,
threedsdemo.simulated-otp-responses.responses[4]=4444,A,01,01,Qm181okmdyqh6yQmYuq1890QAAA=