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
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
 
}

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
public enum ResultsRequestTypeEnum {
 
  /**
   * Results request indicating authenticated transaction.
   */
  AUTHENTICATED_TRANSACTION,
  /**
   * Invalid results request indicating authenticated transaction.
   */
  AUTHENTICATED_TRANSACTION_MISSING_AUTHENTICATION_VALUE,
  /**
   * 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
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.num7654310438720050.rReq=AUTHENTICATED_TRANSACTION
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000012.rReq=AUTHENTICATED_TRANSACTION_MISSING_AUTHENTICATION_VALUE
threedsdemo.cardholderNumbersSimulatedMessageTypes.num4000001000000013.rReq=PROTOCOL_ERROR

Per the Authentication Response configuration, there is also a possibility to configure specific message fields values per authentication response 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
  • THREE_RI - authenticationValue,eci
  • PROTOCOL_ERROR - errorComponent, errorCode, errorDescription, errorDetail

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

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

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
2
3
4
5
6
#startRange,endRange,actionInd,acsStartProtocolVersion,acsEndProtocolVersion,dsStartProtocolVersion,dsEndProtocolVersion
threedsdemo.simulated-card-range-data.ranges[0]=4000000000000000,4000001999999999,A,2.1.0,2.1.0,2.1.0,2.1.0
threedsdemo.simulated-card-range-data.ranges[1]=4000003000000000,4000003999999999,A,2.1.0,2.1.0,2.1.0,2.1.0
threedsdemo.simulated-card-range-data.ranges[2]=4000007000000000,4000007999999999,A,2.1.0,2.1.0,2.1.0,2.1.0
threedsdemo.simulated-card-range-data.ranges[3]=5000001000000000,5000007999999999,A,2.1.0,2.1.0,2.1.0,2.1.0
threedsdemo.simulated-card-range-data.ranges[4]=1000000000000000,1999999999999999,R,2.1.0,2.1.0,2.1.0,2.1.0

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=