3DS Server Integration Manual

Web Service API

3DSecure 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 two 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-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
challenge ThreeDSServerChallengeResponse Send the final Challenge 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.

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

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
/**
 * 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
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<!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="frameContainer01"></div>
<div id="frameContainer02"></div>
<div id="frameContainer03"></div>
<div id="frameContainer04"></div>
<div id="frameContainer05"></div>
<iframe id="iframeContainerFull" name="iframeContainerFull" width="100%" height="100%"></iframe>
 
<script type="text/javascript">
    // Load all containers
    iFrameContainerFull = document.getElementById('iframeContainerFull');
    container01 = document.getElementById('frameContainer01');
    container02 = document.getElementById('frameContainer02');
    container03 = document.getElementById('frameContainer03');
    container04 = document.getElementById('frameContainer04');
    container05 = document.getElementById('frameContainer05');
 
 
    // nca3DSWebSDK.init3DSChallengeRequest(acsUrl, creqData, container);
    nca3DSWebSDK.init3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', iFrameContainerFull);
 
    // nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest(acsUrl, creqData, challengeWindowSize, frameName, rootContainer, callbackWhenLoaded);
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '01', 'threeDSCReq01', container01);
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '02', 'threeDSCReq02', container02);
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '03', 'threeDSCReq03', container03);
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '04', 'threeDSCReq04', container04);
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '05', 'threeDSCReq05', container05, () => {
        console.log('Iframe loaded, form created and submitted');
    });
</script>
 
</body>
</html>