3DS 1.0 NDM Simulator Configuration

Verify Enrollment Response (VERes) configuration

The NDM Simulator allows external configuration of the simulated VERes per account number. This simulates the functionality of 3DS 1.0 Directory Server.

Possible types of VERes are listed below:

  • ENROLLED_Y - VALID_RESPONSE, "Enrolled Y: Authentication Available."
  • ENROLLED_N - VALID_RESPONSE, "Enrolled N: Cardholder Not Participating."
  • ENROLLED_U - VALID_RESPONSE, "Enrolled U: Unable To Authenticate."
  • MISSING_ROOT - INVALID_RESPONSE, "Response with a missing root element."
  • MISSING_MESSAGE - INVALID_RESPONSE, "Response with a missing message element."
  • INVALID_MESSAGE - INVALID_RESPONSE, "Response with an invalid message element."
  • MISSING_VERSION - INVALID_RESPONSE, "VERes with missing version."
  • ILLEGAL_VERSION - INVALID_RESPONSE, "VERes with illegal version."
  • MISSING_URL - INVALID_RESPONSE, "VERes with missing url."
  • ILLEGAL_URL - INVALID_RESPONSE, "VERes with illegal url."
  • MISSING_ENROLLED - INVALID_RESPONSE, "VERes with missing enrolled."
  • ILLEGAL_ENROLLED - INVALID_RESPONSE, "VERes with illegal enrolled."
  • ILLEGAL_EXTENSION - INVALID_RESPONSE, "VERes with illegal extension (id and critical are empty)."
  • ERROR_1 - ERROR_RESPONSE, "Error 1: Root element invalid."
  • ERROR_2 - ERROR_RESPONSE, "Error 2: Message element not a defined message."
  • ERROR_3 - ERROR_RESPONSE, "Error 3: Required element missing."
  • ERROR_4 - ERROR_RESPONSE, "Error 4: Critical element not recognized."
  • ERROR_5 - ERROR_RESPONSE, "Error 5: Format of one or more elements is invalid according to the specification."
  • ERROR_6 - ERROR_RESPONSE, "Error 6: Protocol version too old."
  • ERROR_50 - ERROR_RESPONSE, "Error 50: Acquirer not participating."
  • ERROR_51 - ERROR_RESPONSE, "Error 51: Merchant not participating."
  • ERROR_52 - ERROR_RESPONSE, "Error 52: Password missing."
  • ERROR_53 - ERROR_RESPONSE, "Error 53: Incorrect password."
  • ERROR_58 - ERROR_RESPONSE, "Error 58: Incorrect Common Name value in Client Certificate."
  • ERROR_98 - ERROR_RESPONSE, "Error 98: Transient system failure."
  • ERROR_99 - ERROR_RESPONSE, "Error 99: Permanent system failure."
  • ERROR_CUSTOM - ERROR_RESPONSE, "Custom Error: Custom error with an undefined error code."
  • ERROR_CUSTOM_WITH_DIFFERENT_MESSAGE_ID - ERROR_RESPONSE, "Custom Error: Custom error with different message id."
  • IREQ_50 - IREQ_RESPONSE, "IReq 50: Acquirer not participating."
  • IREQ_51 - IREQ_RESPONSE, "IReq 51: Merchant not participating."
  • IREQ_52 - IREQ_RESPONSE, "IReq 52: Password missing."
  • IREQ_53 - IREQ_RESPONSE, "IReq 53: Incorrect password."
  • IREQ_54 - IREQ_RESPONSE, "IReq 54: ISO code not valid (country or currency)."
  • IREQ_55 - IREQ_RESPONSE, "IReq 55: Transaction data not valid."
  • IREQ_56 - IREQ_RESPONSE, "IReq 56: Cardholder PAN is not in range belonging to issuer."
  • IREQ_58 - IREQ_RESPONSE, "IReq 58: Access denied, invalid endpoint."
  • IREQ_98 - IREQ_RESPONSE, "IReq 98: Transient system failure."
  • IREQ_99 - IREQ_RESPONSE, "IReq 99: Permanent system failure."
  • IREQ_CUSTOM** - IREQ_RESPONSE, "Custom IReq: Custom IReq with an undefined IReq code."
  • IREQ_ENROLLED_Y - IREQ_RESPONSE, "IReq: Enrolled set to Y"
  • UNSUPPORTED_VERSION - OTHER, "VERes with unsupported version."
  • UNRECOGNIZED_CRITICAL_EXTENSION - OTHER, "VERes with an unrecognized critical extension."
  • SERVER_ERROR** - OTHER, "Server Error."
  • TIMEOUT - OTHER, "Timeout: Sleep for 60 seconds."

In order to configure the type of VERes, use the threeds-one-ds-simulator-config.properties configuration file in the $NDM_SIMULATOR_HOME/conf.

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

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 response is ENROLLED_Y.

The 3DS 1.0 ACS URL should be configured there as well using threeds-one-ds-simulator-config.acs-url parameter. The value must be in format: http(s)://NDM Simulator Host:NDM Simulator Port/3ds1/acs/authenticate

An example configuration is listed below:

Payer Authentication Response (PARes) configuration

The NDM Simulator allows external configuration of the simulated PARes and other specific message fields (cavv, cavv algorithm and eci) per account number. This simulates the functionality of 3DS 1.0 ACS.

Possible types of PARes are listed below:

  • TRANSACTION_STATUS_Y - VALID_RESPONSE, "Transaction Status Y: Customer was successfully authenticated."
  • TRANSACTION_STATUS_N - VALID_RESPONSE, "Transaction Status N: Customer failed or cancelled authentication. Transaction denied."
  • TRANSACTION_STATUS_N_WITH_PAN_LAST_4_DIGITS_NOT_MASKED - VALID_RESPONSE, "Transaction Status N with PAN last 4 digits not masked"
  • TRANSACTION_STATUS_U - VALID_RESPONSE, "Transaction Status U: Authentication could not be completed, due to technical or other problem, as indicated in PARes.IReq."
  • TRANSACTION_STATUS_U_WITH_PAN_LAST_4_DIGITS_NOT_MASKED - VALID_RESPONSE, "Transaction Status U with PAN last 4 digits not masked"
  • TRANSACTION_STATUS_A - VALID_RESPONSE, "Transaction Status A: Proof of authentication attempt was generated."
  • TRANSACTION_CHALLENGE_OTP - VALID_RESPONSE, "Transaction OTP challenge required for authentication."
  • CAVV_ALGORITHM_4 - VALID_RESPONSE, "Response with a cavv algorithm 4."
  • MISSING_ROOT - INVALID_RESPONSE, "Response with a missing root element."
  • MISSING_MESSAGE - INVALID_RESPONSE, "Response with a missing message element."
  • MISSING_MESSAGE_ID - INVALID_RESPONSE, "Response with a missing message id attribute."
  • EMPTY_MESSAGE_ID - INVALID_RESPONSE, "Response with a empty message id attribute."
  • INVALID_MESSAGE - INVALID_RESPONSE, "Response with an invalid message element."
  • MISSING_VERSION - INVALID_RESPONSE, "PARes with missing version."
  • INVALID_PARES_ELEMENT_NAME - OTHER, "Changes name of 'PARes' to 'PPRS"
  • UNDEFINED_ELEMENT_IN_MESSAGE - OTHER, "Undefined element in 'Message' before 'PARes' element"
  • ILLEGAL_VERSION - INVALID_RESPONSE, "PARes with illegal version."
  • NOT_SIGNED - VALID_RESPONSE, "Not Signed PARes."
  • ERROR_1 - ERROR_RESPONSE, "Error 1: Root element invalid."
  • ERROR_2 - ERROR_RESPONSE, "Error 2: Message element not a defined message."
  • ERROR_3 - ERROR_RESPONSE, "Error 3: Required element missing."
  • ERROR_4 - ERROR_RESPONSE, "Error 4: Critical element not recognized."
  • ERROR_5 - ERROR_RESPONSE, "Error 5: Format of one or more elements is invalid according to the specification."
  • ERROR_6 - ERROR_RESPONSE, "Error 6: Protocol version too old."
  • ERROR_50 - ERROR_RESPONSE, "Error 50: Acquirer not participating."
  • ERROR_51 - ERROR_RESPONSE, "Error 51: Merchant not participating."
  • ERROR_52 - ERROR_RESPONSE, "Error 52: Password missing."
  • ERROR_53 - ERROR_RESPONSE, "Error 53: Incorrect password."
  • ERROR_58 - ERROR_RESPONSE, "Error 58: Incorrect Common Name value in Client Certificate."
  • ERROR_98 - ERROR_RESPONSE, "Error 98: Transient system failure."
  • ERROR_99 - ERROR_RESPONSE, "Error 99: Permanent system failure."
  • ERROR_CUSTOM - ERROR_RESPONSE, "Custom Error: Custom error with an undefined error code."
  • ERROR_CUSTOM_WITH_DIFFERENT_MESSAGE_ID - ERROR_RESPONSE, "Custom Error: Custom error with different message id."
  • IREQ_50 - IREQ_RESPONSE, "IReq 50: Acquirer not participating."
  • IREQ_51 - IREQ_RESPONSE, "IReq 51: Merchant not participating."
  • IREQ_52 - IREQ_RESPONSE, "IReq 52: Password missing."
  • IREQ_53 - IREQ_RESPONSE, "IReq 53: Incorrect password."
  • IREQ_54 - IREQ_RESPONSE, "IReq 54: ISO code not valid (country or currency)."
  • IREQ_55 - IREQ_RESPONSE, "IReq 55: Transaction data not valid."
  • IREQ_56 - IREQ_RESPONSE, "IReq 56: Cardholder PAN is not in range belonging to issuer."
  • IREQ_58 - IREQ_RESPONSE, "IReq 58: Access denied, invalid endpoint."
  • IREQ_98 - IREQ_RESPONSE, "IReq 98: Transient system failure."
  • IREQ_99 - IREQ_RESPONSE, "IReq 99: Permanent system failure."
  • IREQ_CUSTOM - IREQ_RESPONSE, "Custom IReq: Custom IReq with an undefined IReq code."
  • UNSUPPORTED_VERSION - OTHER, "PARes with unsupported version."
  • UNRECOGNIZED_CRITICAL_EXTENSION - OTHER, "PARes with an unrecognized critical extension."
  • SERVER_ERROR - OTHER, "Server Error."
  • TIMEOUT - OTHER, "Timeout: Sleep for 600 seconds."
  • SIGNATURE_UNTRUSTED_ANCHOR - INVALID_RESPONSE, "PaRes with signature certificate not resolved to trusted anchor."

In order to configure the type of PARes, cavv, cavv algorithm or eci value, use the threeds-one-acs-simulator-config.properties configuration file in the $NDM_SIMULATOR_HOME/conf.

If the card is not present in the configuration file, the default response is TRANSACTION_STATUS_N.

Specific PARes message field values can be configured: cavv, cavv algorithm and eci. They must be specified in that order after the PARes type. If some message field is not configured, a default value will be used. The field values are separated with comma.

The NDM simulator is signing the content of a PARes. The signing certificate store location, alias and password must be configured here as well. The configured certificate information will be used for signing all simulation scenarios responses except for the SIGNATURE_UNTRUSTED_ANCHOR simulation scenario. For this specific scenario, the NDM Simulator generates a certificate itself for signing the PaRes which is unknown to the 3DS Server, thus causing validation error on 3DS Server side which is the intention of this simulation.

An example configuration is listed below:

Challenge Flow Configuration

To configure a pan for challenge flow, set TRANSACTION_CHALLENGE_OTP as PaRes type in the threeds-one-acs-simulator-config.properties configuration file in the $NDM_SIMULATOR_HOME/conf.

The NDM Simulator allows configuration of the challenge data sent when simulating an ACS for Challenge flow. The configurable values are: transaction status, cavv, cavv algorithm and eci. They are configured per OTP code. The values of: cavv, cavv algorithm and eci can be omitted by leaving a blank value, but they must be specified in the particular order. In case a field is not configured, a default value will be used. The configurable values are separated with comma.

In order to configure the challenge data, use the threeds-one-simulated-otp-responses.properties configuration file in the $NDM_SIMULATOR_HOME/conf.

If the otp value is not present in the configuration file, the default response is TRANSACTION_STATUS_N.

An example configuration file is also listed below:

Challenge Template

The Netcetera Demo Merchant Simulator provides a pre-defined HTML template that is returned when initiating a challenge to the simulated ACS Challenge handler. The 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 threeds-one-acs-simulator-config.challenge-template-location configuration property.

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.

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

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

in order for the NDM Simulator to proceed with authentication upon successful handling of the challenge.

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

required for the NDM Simulator to proceed with authentication upon successful handling of the challenge.

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

required for the NDM Simulator to proceed with authentication upon successful handling of the challenge.

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.