3DS Server Configuration

Schema

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
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="ThreeDSServerConfiguration" type="ThreeDSServerConfiguration"/>
 
 
  <!--Configuration types-->
  <!--Root type-->
  <xs:complexType name="ThreeDSServerConfiguration">
    <xs:annotation>
      <xs:documentation>
        <![CDATA[
          The 3DS Server configuration.
        ]]>
      </xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="TimeoutConfiguration" minOccurs="0" type="TimeoutConfiguration">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
              Configuration for timeouts for different message types. Timeout values are specified in milliseconds.
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="UrlConfiguration" type="UrlConfiguration">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
              Contains URLs for communication between the DS, 3DS Server and PSP.
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="Scheme" maxOccurs="unbounded" type="Scheme">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
              Contains Scheme related information (Scheme ID and DS configuration).
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="Acquirer" maxOccurs="unbounded" type="Acquirer" minOccurs="0">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
                Contains Acquirer related information (Acquirer Name, Acquirer BIN configuration, DS configuration).
              ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="Merchant" maxOccurs="unbounded" type="Merchant" minOccurs="0">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
                Contains Merchant related information (Merchant Name, Merchant acquirer information, DS configuration).
              ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
 
  <!--Complex types-->
  <!--Timeout configuration types-->
  <xs:complexType name="TimeoutConfiguration">
    <xs:attribute name="aRes" type="xs:integer">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            The time in seconds to wait for ARes to be sent back. Default value is 300 (seconds).
            For JCB Directory Servers should be set as 8 seconds or more.
            For American Express Directory Servers should be set as 15 seconds.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="pRes" type="xs:integer">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            The time in seconds to wait for PRes to be sent back. Default value is 300 (seconds).
            For JCB Directory Servers should be set as 2 seconds or more.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="threeDSMethod" type="xs:integer">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            The time in seconds to wait for 3DS Method to be sent back. Default value is 10 (seconds).
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
 
  <!--URLs configuration types-->
  <xs:complexType name="UrlConfiguration">
    <xs:sequence>
      <xs:element name="NotificationUrl" type="NotificationUrl">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
              Fully qualified URL of the system that receives the CRes message or Error Message. (Mandatory for AReq).
 
              This is endpoint is used by the ACS to send the final Challenge Response message to the Requestor
              environment via the cardholder's browser. When configured here it will be used for all
              Authentication Request messages. It can be overridden at the Merchant configuration level.
 
              Incorrect formatting will result in a failure to deliver the notification of the final CRes message.
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="ResultsResponseNotificationUrl" type="ThreeDSUrlType">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
              PSP url to which 3DS Server should send the results from RReq.
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="ThreeDSRequestorUrl" type="ThreeDSUrlType" minOccurs="0">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
              Fully qualified URL of 3DS Requestor website or customer care site.
 
              This data element provides additional information to the receiving 3-D Secure system
              if a problem arises and should provide contact information.
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="ThreeDSMethodNotificationUrl" type="ThreeDSUrlType">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
              Fully qualified URL that will receive the notification of 3DS Method completion from the ACS. This is
              sent in the initial request to the ACS from the 3DS Requestor executing the 3DS Method.
 
              3DS Server has an exposed endpoint that can handle 3DS Method Notification responses.
              In order to use that handler configure the ThreeDSMethodNotificationUrl to point to:
              https://<host>:<port>/3ds/3ds-method-notification/
 
              Incorrect formatting will result in a failure to deliver the notification of the 3DS Method completion.
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
 
  <!--Directory Server types-->
  <xs:complexType name="DirectoryServer">
    <xs:sequence>
      <xs:element name="ClientCertificateStore" type="RootCertificateStore" minOccurs="0">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
            The Client Certificate used to authenticate to the Directory Server.
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="TrustCertificateStore" type="RootCertificateStore" minOccurs="0">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
            The Root Certificate used when communicating with the Directory Server.
            The configuration of this element is optional.
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="DirectoryServerEndpoint" type="DirectoryServerEndpoint" minOccurs="0" maxOccurs="unbounded">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
            The list of endpoints provided by this Directory Server.
 
                If communication with the Directory Server fails using an endpoint,
                the 3DS Server will try again with the next endpoint in the list.
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="TimeoutConfiguration" type="TimeoutConfiguration" minOccurs="0">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
            TimeoutConfiguration. If not configured, default timeout in milliseconds will be applied. Check the
                TimeoutConfiguration type declaration for default timeout values.
            ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="threeDSServerOperatorID" type="ThreeDSServerOperatorId">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
              Directory Server assigned Server identifier.
            ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="threeDSServerReferenceNumber" type="ThreeDSServerReferenceNumber" default="3DS_LOA_SER_NEAG_020200_00256">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
              3DS Server Reference Number.
            ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="threeDSServerUrl" type="ThreeDSUrlType">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
              Fully qualified URL of the 3DS Server to which the DS will send the RReq message after the challenge
              has completed.
 
              This URL is used to establish a secure connection between the Directory Server and 3DS Server using
              TLS protocol with mutual authentication. The URL hostname and port need to be the same as the virtual host
              that is configured to authenticate the DS.
              3DS Server has exposed endpoint to handle the incoming RReq message, the URL should be configured to point
              there:
              https://<host>:<port>/3ds/results-request
 
              Incorrect formatting will result in a failure to deliver the transaction results via the RReq message.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="preqEnabled" type="xs:boolean" default="true">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            Can be used to temporarily disable PReq for a Directory Server.
            If disabled, no PReqs would be send for this Directory Server.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="pReqMessageVersion" type="ProtocolVersion" default="2.2.0">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
          The protocol version in the preparation request which the 3DS Server sends to the Directory Server.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
  <xs:complexType name="DirectoryServerEndpoint">
    <xs:attribute name="url" type="xs:anyURI" use="required">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            The URL of the endpoint. The URL is used to post requests from 3DS Server to DS.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="preparationUrl" type="xs:anyURI">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            The URL of the DirectoryServer endpoint where the 3DS Server will post Preparation Requests to.
            If the DirectoryServer has one endpoint for Authentication and Preparation Requests, this field is optional
            and can be omitted. If empty, the DirectoryServerEndpoint#url value will be used.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="enabled" type="xs:boolean" default="true">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            Can be used to temporarily disable and endpoint.
            A disabled endpoint will not be used by the server to communicate with the DS.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
 
  <xs:complexType name="RootCertificateStore">
    <xs:attribute name="keystoreResource" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            The Java keystore resource location.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="keystorePassword" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            The password to access the Java keystore.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
 
  <!--Scheme types-->
  <xs:complexType name="Scheme">
    <xs:sequence>
      <xs:element name="DirectoryServer" type="DirectoryServer">
        <xs:annotation>
          <xs:documentation>
            <![CDATA[
  The Directory Server used by this Scheme.
  ]]>
          </xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="schemeId" type="SchemeId" use="required">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            The ID of the scheme (Visa, Mastercard, JCB, American Express, Diners or any other scheme).
            ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
 
  <!--Acquirer types-->
  <xs:complexType name="Acquirer">
    <xs:annotation>
      <xs:documentation>
        <![CDATA[
          Contains information for the Acquirer name and list of acquirer bins.
        ]]>
      </xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="AcquirerBin" type="AcquirerBin" maxOccurs="unbounded" />
    </xs:sequence>
    <xs:attribute name="name" type="xs:string" use="required" />
    <xs:attribute name="relaxRegionalValidationRules" type="RelaxRegionalValidationRules"/>
  </xs:complexType>
 
  <xs:complexType name="AcquirerBin">
    <xs:annotation>
      <xs:documentation>
        <![CDATA[
          Contains information for value of the BIN and scheme.
        ]]>
      </xs:documentation>
    </xs:annotation>
    <xs:attribute name="schemeId" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            Supported payment schemes.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="value" type="xs:string" use="required" />
  </xs:complexType>
 
  <!--Merchant types-->
  <xs:complexType name="Merchant">
    <xs:annotation>
      <xs:documentation>
        <![CDATA[
          Contains merchant information.
        ]]>
      </xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="MerchantAcquirer" type="MerchantAcquirer" maxOccurs="unbounded" />
    </xs:sequence>
    <xs:attribute name="id" type="xs:string" use="required" />
    <xs:attribute name="merchantName" type="MerchantName" />
    <xs:attribute name="mcc" type="MCC" />
    <xs:attribute name="merchantCountryCode" type="MerchantCountryCode" />
    <xs:attribute name="relaxRegionalValidationRules" type="RelaxRegionalValidationRules"/>
    <xs:attribute name="notificationURL" type="NotificationUrl"/>
  </xs:complexType>
 
  <xs:complexType name="MerchantAcquirer">
    <xs:annotation>
      <xs:documentation>
        <![CDATA[
          Contains information about the acquirer BIN and merchant ID.
        ]]>
      </xs:documentation>
    </xs:annotation>
    <xs:attribute name="acquirerBin" type="xs:string" use="required" />
    <xs:attribute name="acquirerMerchantID" type="AcquirerMerchantId" use="required">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
          Acquirer-assigned Merchant identifier.
        ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="merchantName" type="MerchantName" />
    <xs:attribute name="mcc" type="MCC" />
    <xs:attribute name="merchantCountryCode" type="MerchantCountryCode" />
    <xs:attribute name="threeDSRequestorID" type="ThreeDSRequestorId">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
              Directory Server assigned Requestor identifier.
            ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="threeDSRequestorName" type="ThreeDSRequestorName">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
              Directory Server assigned Requestor name.
            ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name="schemeId" type="xs:string" use="required">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            The ID of the Scheme related to this merchant acquirer. The ID must be the same as the schemeId for the
            AcquirerBIN related to this MerchantAcquirer.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
 
 
  <!--Simple types-->
  <xs:simpleType name="ThreeDSRequestorId">
    <xs:restriction base="xs:string">
      <xs:minLength value="1" />
      <xs:maxLength value="35" />
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="ThreeDSRequestorName">
    <xs:restriction base="xs:string">
      <xs:minLength value="1" />
      <xs:maxLength value="40" />
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="ThreeDSServerOperatorId">
    <xs:restriction base="xs:string">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            DS assigned 3DS Server identifier. Each DS can provide a unique ID to each 3DS Server on an individual basis.
            Requirements for the presence of this field in AReq and PReq messages are DS specific.
            For JCB, American Express and Visa Schemes threeDSServerOperatorId is a required field in AReq and PReq messages.
          ]]>
        </xs:documentation>
      </xs:annotation>
      <xs:minLength value="1" />
      <xs:maxLength value="32" />
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="ThreeDSServerReferenceNumber">
    <xs:restriction base="xs:string">
      <xs:maxLength value="32" />
      <xs:pattern value="[a-zA-Z0-9_]*" />
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="SchemeId">
      <xs:restriction base="xs:string">
          <xs:maxLength value="40" />
          <xs:pattern value="[a-zA-Z0-9\-_ ]*" />
      </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="ThreeDSUrlType">
    <xs:restriction base="xs:anyURI">
      <xs:maxLength value="2048" />
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="NotificationUrl">
    <xs:restriction base="xs:anyURI">
      <xs:maxLength value="256" />
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="AcquirerMerchantId">
    <xs:restriction base="xs:string">
      <xs:maxLength value="35" />
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="MerchantName">
    <xs:restriction base="xs:string">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            Merchant name assigned by the Acquirer or Payment System. This field is limited to maximum 40 characters,
            and it is the same name used in the authorisation message as defined in ISO 8583.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="RelaxRegionalValidationRules">
    <xs:restriction base="xs:boolean">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
          Boolean flag indicating whether the validation for required cardholder data should not be applied in the
          authentication request in case when market or regional mandate restricts sending the information.
          ]]>
        </xs:documentation>
      </xs:annotation>
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="MCC">
    <xs:restriction base="xs:string">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
          Merchant Category Code. The DS-specific code describing the Merchant's type of business, product or service.
          ]]>
        </xs:documentation>
      </xs:annotation>
      <xs:minLength value="4" />
      <xs:maxLength value="4" />
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="MerchantCountryCode">
    <xs:restriction base="xs:string">
      <xs:annotation>
        <xs:documentation>
          <![CDATA[
            Country code for the merchant. This value correlates to the Merchant Country Code as defined by each
                Payment System or DS.
          ]]>
        </xs:documentation>
      </xs:annotation>
      <xs:minLength value="3" />
      <xs:maxLength value="3" />
    </xs:restriction>
  </xs:simpleType>
 
  <xs:simpleType name="ProtocolVersion" final="restriction" >
    <xs:restriction base="xs:string">
      <xs:enumeration value="2.1.0" />
      <xs:enumeration value="2.2.0" />
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Configuration template

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
<?xml version="1.0" encoding="UTF-8"?>
<ThreeDSServerConfiguration>
 
  <!--<TimeoutConfiguration aRes="..." pRes="..."/>-->
 
  <!--<UrlConfiguration>-->
    <!--<NotificationUrl>https://...</NotificationUrl>-->
    <!--<ResultsResponseNotificationUrl>https://...</ResultsResponseNotificationUrl>-->
    <!--<ThreeDSRequestorUrl>https://...</ThreeDSRequestorUrl>-->
    <!--<ThreeDSMethodNotificationUrl>https://...</ThreeDSMethodNotificationUrl>-->
  <!--</UrlConfiguration>-->
 
  <!--<Scheme schemeId="...">-->
    <!--<DirectoryServer threeDSServerOperatorID="..." threeDSServerUrl="https://...">-->
      <!--<ClientCertificateStore keystoreResource="file:" keystorePassword="..."/>-->
      <!--<DirectoryServerEndpoint url="https://..." enabled="..."/>-->
    <!--</DirectoryServer>-->
  <!--</Scheme>-->
 
  <!--<Acquirer name="...">-->
    <!--<AcquirerBin schemeId="..." value="..."/>-->
  <!--</Acquirer>-->
 
  <!--<Merchant id="..." merchantName="..." mcc="..." merchantCountryCode="...">-->
    <!--<MerchantAcquirer acquirerBin="..." acquirerMerchantID="..." schemeId="..." threeDSRequestorID="..."
          threeDSRequestorName="..."/>-->
  <!--</Merchant>-->
 
</ThreeDSServerConfiguration>

Supported scheme configuration naming

All supported scheme configurations should be named accordingly.

  • Visa scheme ID: Visa
  • MasterCard scheme ID: Mastercard
  • American Express scheme ID: American Express
  • JCB scheme ID: JCB
  • Diners scheme ID: Diners
  • MIR scheme ID: Mir
  • Cartes Bancaires scheme ID: CB (For Cartes Bancaires, it is recommended to send the scheme ID)
  • Union Pay scheme ID: UPOP