NDM Simulator Integration with the 3DS Server

3DS Server 2.x

Once the Netcetera Demo Merchant Simulator is up and running, the following endpoints of the NDM Simulator should be configured in the 3DS Server Timeout Configuration:

  • The Results Response Notification Url - fully-qualified-url-of-simulator/requestor/results-notification
  • The Notification Url - fully-qualified-url-of-simulator/requestor/challenge-notification
  • The ThreeDS Requestor Url - fully-qualified-url-of-simulator/shop

Scheme Directory Server configuration

Since the NDM Simulator simulates a Directory Server, Scheme(s) should be configured in the 3DS Server Configuration having the NDM Simulator endpoints as Directory Server endpoints.

For handling authentication requests the NDM Simulator exposes the following endpoint:

  • fully-qualified-url-of-simulator/ds/authentication

This endpoint should be configured as primary endpoint of the Directory Server (in the url property).

For handling preparation requests the NDM Simulator exposes the following endpoints (all simulate different responses):

  • fully-qualified-url-of-simulator/ds/valid-pres-configured-card-range-data
  • fully-qualified-url-of-simulator/ds/valid-pres-add-card-range-data
    • The returned Preparation Response includes the following card ranges having action indicator ADD: [4000001000000000, 4000001999999999], [4000003000000000, 4000003999999999], [4000007000000000, 4000007999999999] and [5000001000000000, 5000007999999999].
  • fully-qualified-url-of-simulator/ds/pres-error-request-validation-failed
    • The returned Preparation Response indicates validation error (invalid threeDSServerRefNumber) in the preparation request.
  • fully-qualified-url-of-simulator/ds/pres-error-request-missing-data
    • The returned Preparation Response indicates missing data in the preparation request.
  • fully-qualified-url-of-simulator/ds/pres-error-request-invalid-serial-num
    • The returned Preparation Response indicates invalid serial number in the preparation request.
  • fully-qualified-url-of-simulator/ds/pres-error-request-sent-messages-limit-exceeded
    • The returned Preparation Response indicates the limit is exceeded for sending preparation request messages.
  • fully-qualified-url-of-simulator/ds/valid-pres-delete-card-range-data
    • The returned Preparation Response includes the following card ranges having action indicator DELETE: [4000003000000000, 4000003999999999].
  • fully-qualified-url-of-simulator/ds/timeout-pres
    • The returned Preparation Response is returned with a timeout of 5 seconds.
  • fully-qualified-url-of-simulator/ds/invalid-pres-missing-data
    • The returned Preparation Response is empty.

Any of the these endpoints could be configured as a preparation endpoint of the Directory Server (in the preparationUrl property).

Best practise would be to configure multiple Schemes, like the example below. At the startup of the 3DS Server it will send preparation requests to all directory servers' preparation endpoints and different types of preparation responses will be simulated from the NDM Simulator.

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
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
<?xml version="1.0" encoding="UTF-8"?>
<ThreeDSServerConfiguration>
 
  <TimeoutConfiguration/>
 
  <UrlConfiguration>
    <NotificationUrl>fully-qualified-url-of-3ds-server/notification</NotificationUrl>
    <ResultsResponseNotificationUrl>fully-qualified-url-of-simulator/requestor/results-notification</ResultsResponseNotificationUrl>
    <ThreeDSRequestorUrl>fully-qualified-url-of-simulator/shop</ThreeDSRequestorUrl>
    <ThreeDSMethodNotificationUrl>fully-qualified-url-of-3ds-server/3ds/3ds-method-notification</ThreeDSMethodNotificationUrl>
  </UrlConfiguration>
 
  <Scheme schemeId="Visa">
    <DirectoryServer  threeDSRequestorID="..." threeDSRequestorName="..." threeDSServerOperatorID="..." threeDSServerUrl="...">
      <ClientCertificateStore keystoreResource="file:..." keystorePassword="..."/>
      <TrustCertificateStore keystoreResource="..." keystorePassword="..."/>
      <DirectoryServerEndpoint
          url="fully-qualified-url-of-simulator/ds/authentication"
          preparationUrl="fully-qualified-url-of-simulator/ds/valid-pres-add-card-range-data" enabled="true"/>
    </DirectoryServer>
  </Scheme>
 
  <Scheme schemeId="...">
  <DirectoryServer threeDSRequestorID="..." threeDSRequestorName="..." threeDSServerOperatorID="..." threeDSServerUrl="...">
    <ClientCertificateStore keystoreResource="file:..." keystorePassword="..."/>
    <TrustCertificateStore keystoreResource="..." keystorePassword="..."/>
    <DirectoryServerEndpoint
        url="fully-qualified-url-of-simulator/ds/authentication"
        preparationUrl="fully-qualified-url-of-simulator/ds/pres-error-request-validation-failed" enabled="true"/>
  </DirectoryServer>
  </Scheme>
      .
      .
      .
      .
      .
  <Scheme schemeId="...">
  <DirectoryServer threeDSRequestorID="..." threeDSRequestorName="..." threeDSServerOperatorID="..." threeDSServerUrl="...">
    <ClientCertificateStore keystoreResource="file:..." keystorePassword="..."/>
    <TrustCertificateStore keystoreResource="..." keystorePassword="..."/>
    <DirectoryServerEndpoint
        url="fully-qualified-url-of-simulator/ds/authentication"
        preparationUrl="fully-qualified-url-of-simulator/ds/invalid-pres-missing-data" enabled="true"/>
  </DirectoryServer>
  </Scheme>
 
  <Acquirer name="...">
    <AcquirerBin schemeId="Visa" value="123456"/>
  </Acquirer>
 
  <Merchant id="..." merchantName="..." mcc="..." merchantCountryCode="...">
    <MerchantAcquirer acquirerBin="123456" acquirerMerchantID="..." schemeId="Visa"/>
  </Merchant>
 
</ThreeDSServerConfiguration>

3DS Server 1.0

Scheme Directory Server configuration

Given that the NDM Simulator simulates a Directory Server, Scheme(s) that are configured in the 3DS Server Configuration should have the NDM Simulator endpoints as Directory Server endpoints.

In case of 3DS 1.0, the Directory Server Endpoint URL should be changed. The screenshot below shows an example Visa scheme configuration with the Endpoint URL http://demo:8080/3ds1/ds/verifyEnrollment

This URL should be adjusted, keeping in mind the format:

  • Host: "demo"
  • Port: "8080"
  • Path: "3ds1/ds/verifyEnrollment"

Additionally, it should be ensured that the Endpoint Authentication Method is CERTIFICATE.

The certificate is specified on the level of AcquirerBin or MerchantAcquirer, as it is described in the 3DS Server documentation.

Visa 3DS 1.0 Directory Server Configuration

UPOP Server

Scheme Directory Server configuration

Given that the NDM Simulator simulates a Directory Server, Scheme(s) that are configured in the 3DS Server Configuration should have the NDM Simulator endpoints as Directory Server endpoints.

In case of UnionPay Online Payment (UPOP), the Directory Server Endpoint should be adjusted. However, the modification is needed only for the "Inquiry URL" field, since the "Backend URL" and "Frontend URL" are used for the Demo - Shop communication and therefore are out of scope for the integration between the Demo and 3DS Server.

The screenshot below shows an example UPOP scheme configuration with the Inquiry URL http://demo:8080/upop/inquiry/status

This URL should be adjusted, keeping in mind the format:

  • Host: "demo"
  • Port: "8080"
  • Path: "upop/inquiry/status"
UPOP Scheme Directory Server Configuration