3DS Server Integration Manual

3DS Server Web Service API

3DS 2.x API

The 3DS Server web services are mapped under /3ds and handle HTTP POST requests. I.e. to initiate authentication, post your request to /3ds/authentication.

The 3DS Server provides the following web service operations to support 3-D Secure transactions:

Operation Request Response Description
versioning ThreeDSServerVersioningRequest ThreeDSServerVersioningResponse Invoke 3DS Method Versioning
authentication ThreeDSServerAuthenticationRequest ThreeDSServerAuthenticationResponse Initiate authentication
challenge-response ThreeDSServerFinalCResRequest ThreeDSServerChallengeResponse Decode, validate and return challenge response
challenge-cancelled Challenge Cancelled Request empty response Notify about challenge cancelled

The 3DS Server web service operations can consume/produce the following media types:

  • application/json

    When calling the web service, specify the media type of your content using the Content-Type HTTP header.

    Refer to the 3DS Server API documentation for details.

Additionally, the 3DS Server will send requests to the 3DS Requestor, if available, for the following operations:

Operation Request Description
results ThreeDSServerResultsResponse Send the Results Response to the Requestor domain

The 3DS Server does not require confirmation of the received data from the Requestor, so no data should be returned. The Requestor should ensure that the configured Requestor endpoints are valid and accessible by the 3DS Server. Refer to the 3DS Server API documentation for details.

There is also one web service which handles GET requests and returns paginated stored 3DS Server card ranges:

Operation Query Parameters Response Description
card-ranges-supported -protocol-versions page (int, required), size (int, required), schemeId (String, optional) PagePResCardRangeDataEntry All available card ranges and supported protocol versions. If schemeId is not sent, card ranges for all schemes are returned.

3DS 1.0 Web Service API

The 3DS 1.0 web services are mapped under /mpi/v1 and handle HTTP POST requests. I.e. to call createPaReqIfEnrolled post your request to /mpi/v1/createPaReqIfEnrolled.

There are two web service operations to support 3-D Secure 1.0 transactions:

Operation Request Response Description
createPaReqIfEnrolled PaReqCreationRequest PaReqCreationResponse Verifies enrollment with the Directory Server and creates the PaReq to be sent to the ACS.
validatePaRes PaResValidationRequest PaResValidationResponse Validates the PaRes returned by the ACS and provides authentication information.

Media Types

The web service operations can consume the following media types:

  • application/x-www-form-urlencoded
  • application/xml
  • application/json

    While they can produce the following media types:

  • application/xml
  • application/json

    When calling the web service, specify the media type of your content using the Content-Type HTTP header and specify the media type you wish to get back in the response using the Accept HTTP header.

Details

Refer to the 3DS 1.0 API documentation for details about the request / response structures and for sample requests.

Union Pay Web Service API

The Union Pay web services are mapped under /upop/v1 and handle HTTP POST requests. I.e. to call createAuthenticationReq post your request to /upop/v1/createAuthenticationReq.

There are three web service operations to support Union Pay transactions:

Operation Request Response Description
createAuthenticationReq AuthReqCreationRequest AuthReqCreationResponse Creates the MsgReq to be sent to UPOP.
validateAuthenticationRes AuthResValidationRequest AuthResValidationResponse Validates the MsgRes returned by UPOP and provides authentication information.
inquireAuthenticationStatus AuthStatusInquiryRequest AuthStatusInquiryResponse Inquires UPOP about the status of a transaction

Media Types

The web service operations can consume the following media types:

  • application/x-www-form-urlencoded
  • application/xml
  • application/json

    While they can produce the following media types:

  • application/xml
  • application/json

    When calling the web service, specify the media type of your content using the Content-Type HTTP header and specify the media type you wish to get back in the response using the Accept HTTP header.

Details

Refer to the UPOP API documentation for details about the request / response structures and for sample requests.

Netcetera 3DS Web SDK

The Netcetera 3DS Web SDK is a lightweight JavaScript that allows merchants to easily invoke 3DS Method and Challenge Request messages for browser-based transactions.

Installation

To install the Netcetera 3DS Web SDK script simply import the JavaScript in the HTML page.

1
2
3
4
5
6
7
8
9
10
11
<!DOCTYPE html>
<html>
    <head>
        ...
        <script src="nca-3ds-web-sdk.js" type="text/javascript" />
        ...
    </head>
    <body>
    ...
    </body>
</html>

The script will attach the nca3DSWebSDK to the JavaScript window object. The nca3DSWebSDK object contain the following operations:

Operation Description
init3DSMethod Create a html structure and attaches a form with one input (threeDSMethodData) and automatically submit it to the threeDSMethodUrl
createIframeAndInit3DSMethod Create an iframe with a html structure and attach a form with one input (threeDSMethodData) and automatically submit it to the threeDSMethodUrl and attach the frame to the container. If specified, a callback will be executed when the frame is loaded.
init3DSChallengeRequest Create a html structure and attaches a form with one input (creq) and automatically submit it to the acsUrl
createIFrameAndInit3DSChallengeRequest Create an iframe with a html structure and attach a form with one input (creq) and automatically submit it to the acsUrl and attach the frame to the container. If specified, a callback will be executed when the frame is loaded.

Technical documentation on the Netcetera 3DS Web SDK and examples for usage can be found below.

Netcetera 3DS Web SDK Technical documentation

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
/**
 * Creates an iframe, attach it to the rootContainer and submit 3DS Method form.
 *
 * @param threeDSMethodUrl - a FQDN endpoint to submit the 3DS Method request
 * @param threeDSMethodData - Base64-encoded 3DS Method Data value
 * @param frameName - name of the frame container. if not set it will be set to 'threeDSMethodIFrame'
 * @param rootContainer - the container where the iframe will be attached to.
 *                        If not set defaults to the JavaScript document.body object
 * @param onFrameLoadCallback - callback function attached to the iframe.onload event
 * @throws {Error} - throws error if there is a validation error
 * @returns {HTMLIFrameElement} - returns the generated iframe element
 */
nca3DSWebSDK.createIframeAndInit3DSMethod = createIframeAndInit3DSMethod;
/**
 * Initiates a 3DS Method request and submits the form the the 3DS Method URL. It will automatically hide the container
 * when initiating a 3DS Method request.
 *
 * @param threeDSMethodUrl - a FQDN endpoint to submit the 3DS Method request
 * @param threeDSMethodData - Base64-encoded 3DS Method Data value.
 * @param container - the iframe container where the form will be attached to. The container must have the 'name'
 *                    attribute set
 * @throws {Error} - throws error if there is a validation error
 * @returns {HTMLIFrameElement} - the container
 */
nca3DSWebSDK.init3DSMethod = init3DSMethod;
/**
 * Initiates a 3DS Challenge request and submits the form the the ACS URL.
 *
 * @param acsUrl - the FQDN URL to submit the Challenge Request
 * @param creqData - Base64-encoded Challenge Request
 * @param container - the iframe container where the form will be attached to. The container must have the 'name'
 *                    attribute set
 * @throws {Error} - throws error if there is a validation error
 * @returns {HTMLIFrameElement} - the container
 */
nca3DSWebSDK.init3DSChallengeRequest = init3DSChallengeRequest;
/**
 * Creates an iframe, attach it to the rootContainer and submits 3DS Challenge Request.
 * @param acsUrl - the FQDN URL to submit the Challenge Request
 * @param creqData - Base64-encoded Challenge Request
 * @param challengeWindowSize - EMVCo assigned window size.
 *                              '01' -> 250px x 400px,
 *                              '02' -> 390px x 400px,
 *                              '03' -> 500px x 600px,
 *                              '04' -> 600px x 400px,
 *                              '05' -> Full screen, or full container content
 * @param frameName - name of the frame container. if not set it will be set to 'threeDSCReqIFrame'
 * @param rootContainer - the container where the iframe will be attached to.
 *                        If not set defaults to the JavaScript document.body object
 * @param onFrameLoadCallback - callback function attached to the iframe.onload event
 * @throws {Error} - throws error if there is a validation error
 * @returns {HTMLIFrameElement} - returns the generated iframe element
 */
nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest = createIFrameAndInit3DSChallengeRequest;
 
window.nca3DSWebSDK = nca3DSWebSDK;

Init 3DS Method Request - Example

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
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <script src="nca-3ds-web-sdk.js" type="text/javascript"></script>
    <title>Init 3DS Method - Example</title>
</head>
<body>
<!-- The first example shows how to generate a form and attach to an already defined iframe -->
<iframe name="iframeContainer" id="iframe"></iframe>
 
<!-- In the second example it will generate an iframe and attach to the #frameContainer element -->
<div id="frameContainer"></div>
 
<script type="text/javascript">
    iframe = document.getElementById('iframe');
    frameContainer = document.getElementById('frameContainer');
    // nca3DSWebSDK.init3DSMethod(threeDSMethodUrl, threeDSMethodData, container);
    nca3DSWebSDK.init3DSMethod('http://example.com', 'base64-encoded-3dsmethod-request', iframe);
 
    // nca3DSWebSDK.createIframeAndInit3DSMethod(threeDSMethodUrl, threeDSMethodData, frameName, rootContainer, callbackWhenLoaded);
    nca3DSWebSDK.createIframeAndInit3DSMethod('http://example.com', 'base64-encoded-3dsmethod-request', 'threeDSMethodIFrameContainer', frameContainer, () => {
        console.log('Iframe loaded, form created and submitted');
    });
</script>
 
</body>
</html>

Init 3DS Challenge Request - Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <script src="nca-3ds-web-sdk.js" type="text/javascript"></script>
    <title>Init 3DS Challenge Request - Example</title>
</head>
<body>
<!-- This example will show how to initiate Challenge Reqeuests for different window sizes. -->
<div id="frameContainer05"></div>
 
<script type="text/javascript">
    container05 = document.getElementById('frameContainer05');
 
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://localhost:8080/acs/challenge', 'ewogICAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjogIjhhODgwZGMwLWQyZDItNDA2Ny1iY2IxLWIwOGQxNjkwYjI2ZSIsCiAgICAiYWNzVHJhbnNJRCI6ICJkN2MxZWU5OS05NDc4LTQ0YTYtYjFmMi0zOTFlMjljNmIzNDAiLAogICAgIm1lc3NhZ2VUeXBlIjogIkNSZXEiLAogICAgIm1lc3NhZ2VWZXJzaW9uIjogIjIuMS4wIiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjogIjAxIiwKICAgICJtZXNzYWdlRXh0ZW5zaW9uIjogWwogICAgICB7CiAgICAgICAgIm5hbWUiOiAiZW12Y29tc2dleHRJbkNoYWxsZW5nZSIsCiAgICAgICAgImlkIjogInRjOFF0bTQ2NUxuMUZYMG5acHJBIiwKICAgICAgICAiY3JpdGljYWxpdHlJbmRpY2F0b3IiOiBmYWxzZSwKICAgICAgICAiZGF0YSI6ICJtZXNzYWdlRXh0ZW5zaW9uRGF0YUluQ2hhbGxlbmdlIgogICAgICB9CiAgICBdCiAgfQ', '05', 'threeDSCReq05', container05, () => {
        console.log('Iframe loaded, form created and submitted');
    });
</script>
 
</body>
</html>