Guides

3-D Secure (3DS)

Integration Guide

Suggest Edits

For extra fraud protection, the 3-D Secure 2.0 (3DS2) protocol requires certain information about the customer’s device to recognize the overall risk for a given transaction. This process of collecting device information for risk-based analysis is called device fingerprinting.

Due to merchant requirements across multiple regions, the system must identify what Device Data Collection (DDC) needs on a platform level. To fulfill this requirement, the POP system should be able to support this feature for 3DS2-opted payments.

Workflow

The steps below describe the basic workflow of a 3DS check during a transaction:

  1. Authorize request - The customer clicks the payment button, prompting the merchant's front-end application to send an Authorize request to CellPoint Digital's Velocity API.

  2. Authorize response - The API returns an Authorize response containing HTML and an expiration time.

  3. Display verification prompts - The front-end application loads the HTML from the Authorize response and displays verification prompts. The customer answers the prompts.

  4. Capture verification results - The front-end application tracks the elapsed time and captures the results of verification, leading to timeout, success, or failure.

  5. Authorize request - The front-end application sends the API a second Authorize request, which contains the verification results.

Prerequisite

Work with your CellPoint Digital sales representative or account manager to sign up, set up your test account, and access your testing credentials, and to sign up for the 3DS feature.

Integration

Complete the following steps to use 3DS with your integration.

1. Send an Authorize request

Endpoint: /mpoint/authorize-payment
Method: POST

When your customer selects the payment button, send a POST request to CellPoint Digital's Velocity API with the transaction details in the request body as normal. See Authorize Payment for details on sending your Authorize request.

If the value of the code attribute in the <status> tag in the response is 2005 or 200501, the transaction requires additional verification:

  • 2005 - 3DS verification required
  • 200501 - DDC verification required

The code below is an example of an Authorize response for a transaction that requires DDC verification:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<status code="200501">DDC verification required for Authorization</status>
	<web-method>{{html encoded data}}</web-method>
	<expiry>{{in_millisecond}}</expiry>	
</root>

If verification is required, the <web-method> tag contains the following:

  • HTML that must be loaded into your application
  • An expiration time in milliseconds, which you will use in the next steps

2. Load the content from <web-method> on your page

Add the entire contents from the <web-method> element on your page.

The example below shows the code from the <web-method> element in the Authorize response:

<html> 
    <head/> 
    <body> 
    <iframe id="Nuvei3ds" name="Nuvei3ds" hidden="hidden"> 
        <input name="iframeplaceholder" type="hidden" disabled="disabled"/> 
    </iframe>
    <form name="frm" method="POST" action="https://3dsn.sandbox.safecharge.com/ThreeDSMethod/api/ThreeDSMethod/threeDSMethodURL" id="threeDSForm" target="Nuvei3ds">
        <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImM3NWM1NzQ0LWU5NWEtNDAyOC1iYzI4LWMzNWIzZTFlYTVjZiIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3ZhLnVhdC0wMS5jZWxscG9pbnRtb2JpbGUubmV0L21wb2ludC9hZ2dyZWdhdG9yL251dmVpL2F1dGhlbnRpY2F0aW9uLWFjayJ9"/>
    </form>
    <script type="text/javascript">
      window.addEventListener("message",(function(e){let t={device_data_info:{id:"","collection_time":null,"expired":!1}};if("https://va.uat-01.cellpointmobile.net"===e.origin){t.device_data_info.id=e.data;let i=new CustomEvent("onDDCComplete",{detail:t});window.dispatchEvent(i)}}),!1);var threeDSForm=document.querySelector("#threeDSForm");if(threeDSForm){threeDSForm.submit();}
    </script> 
    </body> 
</html>

The iframe will collect the verification data. Your customer will need to complete the verification by either answering prompts about their identity or entering a one-time passcode sent to their mobile device or email address. The verification method depends on the type of verification (3DS or DDC) and the credit card company.

3. Handle the verification process and results

Your page must include functions that track the status of the verification process and capture the results. Your code should perform three functions:

  • Track the elapsed time in milliseconds and trigger a timeout if necessary.
  • Catch the success event and capture the verification results.
  • POST the results (timeout or success) to the API using a second call to /authorize.

The verification will lead to one of the three following results:

  • Timeout - The verification took more than <expiry value> milliseconds.
  • Success - The customer successfully verified their identity.
  • Failure - The customer failed to verify their identity.

The sections below describe what to do in each case:

Timeout

If the verification times out, send a second POST request to the /authorize endpoint containing a <device_data_info> element with the collection time in milliseconds and the value of <expired> set to true.

The example below shows the <device_data_info> element for a timeout request:

<device_data_info>	
	<collection_time>{{in_millisecond}}</collection_time>
	<expired>true</expired>	
</device_data_info>

Success and Failure

CellPoint Digital returns the results of the identity verification in JSON. Capture the values of id, collection_time, and expired. Send a POST request to the /authorize endpoint with a <device_data_info> element containing the verification results.

The code below shows and example of a response from CellPoint:

{
		"id": "{{ddc_id}}",
		"collection_time": "{{in_millisecond}}",
		"expired": "{{boolean}}",
		"additional_info": {
			"info": [
				{
					"key": "{{key}}",
					"value": "{{value}}"
				},
				{
					"key": "{{key}}",
					"value": "{{value}}"
				}
			]
		}
	}

And the code below shows the structure of the <device_data_info> element in a request to the /authorize endpoint:

<device_data_info>
	<id>{{ddc_id}}</id>
	<collection_time>{{in_millisecond}}</collection_time>
	<expired>{{boolean}}</expired>
	<additional_info>
		<info>
			<key>{{key}}</key>
			<value>{{value}}</value>
		</info>
		<info>
			<key>{{key}}</key>
			<value>{{value}}</value>
		</info>
	</additional_info>
</device_data_info>

Sample Code

The code below is an example of how to use JavaScript to add functions to your site that handle the timeout and success/failure conditions:

<script type="text/javascript">
    //START - Sample Script for Reference
    let isDDCComplete = false;
    const date1 = new Date();
    const ddcStartTime = date1.getTime();
    const ddcTimeout = setTimeout(onDDCTimeout, 10000); // Set Timeout - Use timeout value from ddc-expiry node of 1st Auth response

    function onDDCTimeout() { // Remove the onDDCComplete event listener to text the Timeout flow
        if(isDDCComplete === false) {
            isDDCComplete = true;
            const date2 = new Date();
            const ddcEndTime = date2.getTime();
            const diffInMs = ddcEndTime - ddcStartTime;
            let device_data_info = {"device_data_info": {"collection_time": diffInMs, "expired": true}}
            console.log("timeout", device_data_info);
            useDeviceData(device_data_info);
        }
    }


    window.addEventListener("onDDCComplete",function(event) { // Once DDC is complete event will receive with DDC details
        if(isDDCComplete == false) {
            isDDCComplete = true;
            const date2 = new Date();
            const ddcEndTime = date2.getTime();
            const diffInMs = ddcEndTime - ddcStartTime;
            let device_data_info = event.detail;
            device_data_info.device_data_info.collection_time = diffInMs;
            console.log("Event Data", device_data_info);
            useDeviceData(device_data_info);
        }
    }, false);

    function useDeviceData(deviceData)
    {
        console.log('Final Data', deviceData);
        // convert to xml and send in 2nd Auth request;
    }

    //END - Sample Script for Reference

</script>

4. Proceed with the transaction as normal

See Authorize Payment for details on completing the transaction. If the identity verification timed out or failed, CellPoint Digital will return an appropriate response and you can let your customer retry the purchase. If the identity verification succeeded, your customer can complete the purchase as normal.

Updated 3 days ago