3D Secure 2

Requirements

All Converge integrators that want to use 3D Secure 2 must be integrating with a terminal that meets the following requirements.

Region set to USA or Canada.
Market Segment set to Internet.
3D Secure 2.0 terminal setting enabled.

Authentication Fields

Pass the following Issuer Authentication variables to authenticate:

Field Name	Description	Required	Length	Data Type
`ssl_3dsecure_value`	Cardholder Authentication Verification Value or CAVV	Conditional	80	Base64 Encoded
`ssl_3ds_message_version`	Message Version	Conditional	20	alphanumeric
`ssl_3ds_server_trans_id`	3DS Server Transaction ID	Conditional	50	alphanumeric
`ssl_3ds_trans_status`	Transaction Status	Conditional	1	alphanumeric
`ssl_3ds_trans_status_reason`	Transaction Status Reason	Conditional	20	alphanumeric
`ssl_dir_server_tran_id`	Direct Server Transaction Identification (ID)	Conditional	50	alphanumeric
`ssl_eci_ind`	eCommerce Indicator Valid values: `5` - Fully authenticated (if eci = 01/1 or 05/5) `6` - Attempted VbV (if eci = 02/2 or 06/6) `7` - Not Authenticated (if eci = 03/3 or 07/7 or not available)	Required	1	numeric
`ssl_program_protocol`	2	Conditional	1	numeric

Integration Methods

3D Secure 2 support is available for the following integration methods:

Hosted Payments Page
Lightbox
Buy Button/Payment Link
Billing and Invoicing
Checkout.js
XML API
Magento plugin
Woocommerce plugin

Hosted Payments Page

The Hosted Payments Page automatically uses 3D Secure 2 for all transactions made using a terminal that meets the general requirements for using 3D Secure 2 with Converge. No additional steps than those listed under General Requirements are necessary.

Lightbox

Lightbox automatically uses 3D Secure 2 for all transactions made using a terminal that meets the general requirements for using 3D Secure 2 with Converge. No additional steps than those listed under General Requirements are necessary.

Buy Buttons and Links

The Buy Buttons and Links automatically use 3D Secure 2 for all transactions made using a terminal that meets the general requirements for using 3D Secure 2 with Converge. No additional steps than those listed under General Requirements are necessary.

Billing and Invoicing

Transactions created using Converge Invoices generated in the Converge UI or using the Billing and Invoicing API automatically use 3D Secure 2 for all transactions made using a terminal that meets the general requirements for using 3D Secure 2 with Converge. No additional steps than those listed under General Requirements are necessary.

Checkout.js

Initiate the Checkout.js Session

Initiate the checkout.js session using the default initiation process.

3DS 2 Web SDK Demo (UAT) endpoint:https://uat.libs.fraud.eu.elavonaws.com/sdk-web-js/0.13.10/3ds2-web-sdk.min.jsLink opens new window

3DS 2 Web SDK Production endpoint:https://libs.fraud.elavongateway.com/sdk-web-js/0.13.10/3ds2-web-sdk.min.jsLink opens new window

The following HTML form demonstrates a test form for implementing a Checkout.js page with 3D Secure 2.

<!DOCTYPE HTML>
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <title>Embedded Payment Demo</title>
    <script
    src="https://code.jquery.com/jquery-3.5.1.js"
    integrity="sha256-QWo7LDvxbWT2tbbQ97B53yJnYU3WhH/C8ycbRAkjPDc="
    crossorigin="anonymous"></script>
    <script>
        var envs = {
            DEMO: "demo.convergepay.com",
            PROD: "www.convergepay.com"
        };
        function loadScript () {
            var id = 'id_checkout_js';
            var id_efs = 'id_efs_js';
            var src = "https://" + envs[$("#env").val()] + "/hosted-payments/Checkout.js"; 
            var srcEfs = ""; 
            if ($("#env").val() === 'PROD'){
                srcEfs = "https://libs.fraud.elavongateway.com/sdk-web-js/1.0.5/3ds2-web-sdk.min.js";
           } else {
                srcEfs = "https://uat.libs.fraud.eu.elavonaws.com/0.9.8/3ds2-web-sdk.min.js";
           }

            delete window.ConvergeEmbeddedPayment;
            $("#" + id).remove();
            $("#" + id_efs).remove();
            var script = document.createElement('script');
            script.setAttribute('id', id);
            script.setAttribute('src', src);
            document.head.appendChild(script);
            var script1 = document.createElement('script');
            script1.setAttribute('id', id_efs);
            script1.setAttribute('src', srcEfs);
            document.head.appendChild(script1);
        }
        $( document ).ready(function() {
             console.log( "ready!" );
             loadScript();
        });

        var transactionToken;
    var efsToken;

        var callback = {
            onError: function (error) {
                showResult("error", error);
            },
            onDeclined: function (response) {
                showResult("declined", JSON.stringify(response));
            },
            onApproval: function (response) {

                showResult("approval", JSON.stringify(response));
            },
            onCancelled: function () {
                showResult("cancelled", "");
            },
            onThreeDSecure2: function (response) {
                console.log("3ds2 token response:");
                console.log(response);
                if (response.ssl_3ds2_token){
                    efsToken = response.ssl_3ds2_token;
                    $("#efsToken").html(efsToken);
                } else {
                    efsToken ="";
                    $("#efsToken").html("Error");
                    }
            }
        };

        function initiateCheckoutJS () {
            var tokenRequest = {
                ssl_amount: $("#ssl_amount").val()
            };
            $.post("checkoutjscurlrequestdevportal.php", tokenRequest, function(data) {
                $("#token").html(data);
                transactionToken = data;
                //getEfsToken();
            });
            return false;
        }

        function getEfsToken() {
            var paymentData = {
                ssl_txn_auth_token: transactionToken
            };
            ConvergeEmbeddedPayment.getEFSToken(paymentData, callback);
            return false;
        }

        function payWithCreditCard () {
            var paymentData = {
                ssl_txn_auth_token: transactionToken,
                ssl_card_number: $("#ssl_card_number").val(),
                ssl_exp_date: $("#ssl_exp_date").val(),
                ssl_cvv2cvc2: $("#ssl_cvv2cvc2").val(),
                ssl_program_protocol: $("#ssl_program_protocol").val(),
                ssl_dir_server_tran_id: $("#ssl_dir_server_tran_id").val(),
                ssl_eci_ind: $("#ssl_eci_ind").val(),
                ssl_3dsecure_value: $("#ssl_3dsecure_value").val(),
		ssl_3ds_message_version: $("#ssl_3ds_message_version").val(),
                ssl_3ds_trans_status: $("#ssl_3ds_trans_status").val(),
                ssl_3ds_trans_status_reason: $("#ssl_3ds_trans_status_reason").val(),
                ssl_3ds_server_trans_id: $("#ssl_3ds_server_trans_id").val()
            };
            ConvergeEmbeddedPayment.pay(paymentData, callback);
            return false;
        }

        function showResult (status, msg, hash) {
            document.getElementById('txn_status').innerHTML = "<b>" + status + "</b>";
            document.getElementById('txn_response').innerHTML = msg + "</b>";
            document.getElementById('txn_hash').innerHTML = hash;
        }

    function getEFSExpiry () {
        var expMM = $("#ssl_exp_date").val().substring(0,2);
        var expYY = $("#ssl_exp_date").val().substring(2,4);
        return expYY.concat(expMM);
    };

    function getEFSEci(eci) {
        if (eci === '01' || eci === '05'){
            return '5';
        } else if (eci === '02' || eci === '06'){
            return '6';
        } else {
            return '7';
        }
    };

        function handleAllInOne() {
    if ($("#env").val() == 'PROD'){
        efsUrl = "https://gw.fraud.elavongateway.com/3ds2";
    } else {
        efsUrl = "https://uat.gw.fraud.eu.elavonaws.com/3ds2"; 
    }
        var sdk = new window.Elavon3DSWebSDK({ baseUrl : efsUrl, token : efsToken, el : 'holder' });

            var request = {
              //challengeIframeElement: document.getElementById('holder'),
              purchaseAmount : $("#ssl_amount").val()*100,
              purchaseCurrency : "840",
              purchaseExponent : "2",
              //purchaseDate : "20200429112659",
              acctNumber : $("#ssl_card_number").val(),
              cardExpiryDate : getEFSExpiry(),
              messageCategory : "01",
              transType : "01",
              threeDSRequestorAuthenticationInd : "01",
              challengeWindowSize: "03",
              displayMode: "lightbox"
        };
 
        sdk.web3dsFlow(request).then( function success(response) {
		document.getElementById('ssl_eci_ind').value = getEFSEci(response.eci);
		document.getElementById('ssl_program_protocol').value = 2;
            	if (response.authenticationValue) {
			document.getElementById('ssl_3dsecure_value').value = response.authenticationValue;
		}
		if(response.dsTransID){
			document.getElementById('ssl_dir_server_tran_id').value = response.dsTransID;
	    	}
                if(response.threeDSServerTransID){
			document.getElementById('ssl_3ds_server_trans_id').value = response.threeDSServerTransID;
		}
		if(response.transStatus){
			document.getElementById('ssl_3ds_trans_status').value = response.transStatus;
		}
		if(response.transStatusReason){
			document.getElementById('ssl_3ds_trans_status_reason').value = response.transStatusReason;
		}
		if(response.messageVersion){
			document.getElementById('ssl_3ds_message_version').value = response.messageVersion;
		} 		
        }, function error(response) {
            console.log("Error " + response);
             document.getElementById('ssl_eci_ind').value = "7";

        });
        }
        </script>
  </head>
  <body leftmargin="20">
  Environment:
                <select id="env" name="env" onchange="loadScript()">
                    <option value="DEMO">DEMO</option>
                    <option value="PROD">Production</option>
                </select><br><br>
                <h3>Step 1: Initiate Checkout</h3>
        <form name="getSessionTokenForm">
            Transaction Amount: <input type="text" id="ssl_amount" name="ssl_amount" value="1.00"> <br> <br>
            <button onclick="return initiateCheckoutJS();">Initiate Checkout.js</button> <br>
        </form>
        <br>
        Transaction Token: <span id="token"></span><br><br>
        <h3>Step 2: Get EFS Token</h3>
        <button onclick="return getEfsToken();">Get EFS Token</button><br><br>
        EFS Token: <span id="efsToken"></span><br><br>
        <h3>Step 3: Process 3DS2</h3>
            Card Number: <input id="ssl_card_number" type="text" name="ssl_card_number" value=""> <br/>
            Expiry Date: <input id="ssl_exp_date" type="text" name="ssl_exp_date" value=""> <br/>
            CVV2: <input id="ssl_cvv2cvc2" type="text" name="ssl_cvv2cvc2" value=""> <br/><br/>

            <button onclick="handleAllInOne()">Process 3DS2</button><br><br>

        <form name="creditCardForm">
            	Program protocol: <input id="ssl_program_protocol" type="text" name="ssl_program_protocol" value="" ><br/>
            	Dir Server: <input id="ssl_dir_server_tran_id" type="text" name="ssl_dir_server_tran_id" value="" ><br/>
            	Eci: <input id="ssl_eci_ind" type="text" name="ssl_eci_ind" value="" ><br/>
            	AuthenticationValue: <input id="ssl_3dsecure_value" type="text" name="ssl_3dsecure_value" value="" ><br/>
	 	3DS Message_version: <input id="ssl_3ds_message_version" name="ssl_3ds_message_version" value=""><br/>
		3DS Trans_status: <input id="ssl_3ds_trans_status" name="ssl_3ds_trans_status" value=""><br/>
		3DS Trans_status_reason: <input id="ssl_3ds_trans_status_reason"  name="ssl_3ds_trans_status_reason" value=""><br/>
		3DS Server_trans_id: <input id="ssl_3ds_server_trans_id" name="ssl_3ds_server_trans_id" value=""><br/>
            <h3>Step 4: Process Payment</h3>
            <button onclick="return payWithCreditCard();">Pay With Credit Card</button> 
        </form>
        <br/>
        <br>
        Status:<div id="txn_status"></div>
        <br>
        Response:<div id="txn_response"></div>
        <br>
        Hash Value:<div id="txn_hash"></div>
  </body>
</html>

Create a serverside script to safely handle the information collected from the form.

<?php
 // Set variables
$merchantID = "XXXXXX"; //Converge 6 or 7-Digit Account ID *Not the 10-Digit Elavon Merchant ID*
$merchantUserID = "XXXXXX"; //Converge User ID *MUST FLAG AS HOSTED API USER IN CONVERGE UI*
$merchantPinCode = "XXXXXX"; //Converge PIN (64 CHAR A/N)
$url = "https://demo.convergepay.com/hosted-payments/transaction_token"; // URL to Converge session token server

/*Payment Field Variables*/
// In this section, we set variables for posted parameters to be captured by the PHP file and passed to Converge in the curl request.
//$firstname=$_POST['ssl_first_name']; //Post first name
//$lastname=$_POST['ssl_last_name']; //Post last name
$amount= $_POST['ssl_amount']; //Post Tran Amount
//$merchanttxnid = $_POST['ssl_merchant_txn_id']; //Capture user-defined ssl_merchant_txn_id as POST data
//$invoicenumber = $_POST['ssl_invoice_number']; //Capture user-defined ssl_invoice_number as POST data

//Follow the above pattern to add additional fields to be sent in curl request below.
$ch = curl_init();    // initialize curl handle
curl_setopt($ch, CURLOPT_URL,$url); // set url to post to
curl_setopt($ch,CURLOPT_POST, true); // set POST method
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set up the post fields. If you want to add custom fields, you would add them in Converge, and add the field name in the curlopt_postfields string.
curl_setopt($ch,CURLOPT_POSTFIELDS,
"ssl_merchant_id=$merchantID".
"&ssl_user_id=$merchantUserID".
"&ssl_pin=$merchantPinCode".
"&ssl_transaction_type=CCSALE"//.
//"&ssl_first_name=$firstname".
//"&ssl_last_name=$lastname".
//"&ssl_get_token=Y".
//"&ssl_add_token=Y"
."&ssl_amount=$amount"
);

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_VERBOSE, true);

$result = curl_exec($ch); // run the curl process
curl_close($ch); // Close cURL

echo $result;  //shows the session token.
?>

XML API

Get the EFS Token with XML API

Get EFS Token

Send a request using the EFStoken transaction type to the Converge API.

xmldata=
<txn>
    <ssl_merchant_ID>my_merchant_id</ssl_merchant_ID>
    <ssl_user_id>my_user_id</ssl_user_id>
    <ssl_pin>my_pin</ssl_pin>
    <ssl_transaction_type>EFSTOKEN</ssl_transaction_type>
</txn>

The API will return an EFS token with the tag ssl_3ds2_token.

<txn>
    <ssl_3ds2_token>
    eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJDb252ZXJnZTIiLCJzY29wZSI6WyIzZHMyOmF1dGhlbnRpY2F0ZSIsIm1lcmNoYW50QWxpYXM6ZEgybUtEVnhNN0I3UXc4MmRjM2c5eWtIIl0sImV4cCI6MTU5MDE3Mzg0NywianRpIjoiNGY4ZTdmNDUtZjI2Ny00YWU3LWJjZjEtMDJhMTUyYzE4MGFkIiwiY2xpZW50X2lkIjoiQ29udmVyZ2UyIn0.qbYzGz8DPKCsY1ex6_1jf5fWNDgHXyze_q6NWctSgyVeMnPlDE61m4mchwEZdMaEWCdga1LMFL3QZGaJTSeDPaFAYqJRy8p_nYdadyBZEOjOrxvjLmFtgVpNhKCztU_MvvFMiMS7XG6nbhJ3uGgLc_TCtJNukET5krh142XUDtQ4FxoTFp8Hqvv2EMgnaw3W0gJEf7rsH5s0sT0K_93CBifo7TjBkyJOWWz7hMgbDC96SH9oF7pXYAi6-3GnozC2VYbdgBA9idjJ2plGWOuEbT8DAK5rZD9y3W0KN0JxBOpeOztUMt_GucFbTYbz92fmAg2CNHL9a0YZ0sUuSMpW0A
    </ssl_3ds2_token>
    <ssl_3ds2_exp>598</ssl_3ds2_exp>
</txn>

Retain this value for the next steps.

Initiate 3D Secure 2 Authentication

Use EFS Token and initiate the 3DS2 Authentication Process and obtain the ECI, CAVV, and Directory Server ID values.

The following example shows a function to handle initiating 3D Secure 2 Authentication using the 3D Secure Web SDK.

function handleAllInOne() {
if ($("#env").val() === 'PROD'){
    efsUrl = "https://gw.fraud.elavongateway.com/3ds2";
} else {
    efsUrl = "https://uat.gw.fraud.eu.elavonaws.com/3ds2";
}
var sdk = new window.Elavon3DSWebSDK({ baseUrl : efsUrl, token : efsToken, el : 'holder' });
    
    var request = {
    purchaseAmount : $("#ssl_amount").val()*100,
    purchaseCurrency : "840",
    purchaseExponent : "2",
    acctNumber : $("#ssl_card_number").val(),
    cardExpiryDate : getEFSExpiry(),
    messageCategory : "01",
    transType : "01",
    threeDSRequestorAuthenticationInd : "01",
    challengeWindowSize: "03",
    displayMode: "lightbox"
};

sdk.web3dsFlow(request).then( function success(response) {
		document.getElementById('ssl_eci_ind').value = getEFSEci(response.eci);
		document.getElementById('ssl_program_protocol').value = 2;
            	if (response.authenticationValue) {
			document.getElementById('ssl_3dsecure_value').value = response.authenticationValue;
		}
		if(response.dsTransID){
			document.getElementById('ssl_dir_server_tran_id').value = response.dsTransID;
	    	}
                if(response.threeDSServerTransID){
			document.getElementById('ssl_3ds_server_trans_id').value = response.threeDSServerTransID;
		}
		if(response.transStatus){
			document.getElementById('ssl_3ds_trans_status').value = response.transStatus;
		}
		if(response.transStatusReason){
			document.getElementById('ssl_3ds_trans_status_reason').value = response.transStatusReason;
		}
		if(response.messageVersion){
			document.getElementById('ssl_3ds_message_version').value = response.messageVersion;
		} 		
        }, function error(response) {
            console.log("Error " + response);
             document.getElementById('ssl_eci_ind').value = "7";

});

Process a Sale

Process a credit card sale transaction with the ECI, CAVV, and Directory Server ID values.

<txn>
    <ssl_merchant_ID>my_merchant_id</ssl_merchant_ID>
    <ssl_user_id>my_user_id</ssl_user_id>
    <ssl_pin>my_pin</ssl_pin>
    <ssl_transaction_type>ccsale</ssl_transaction_type>
    <ssl_card_number>0000000000000000</ssl_card_number>
    <ssl_exp_date>1220</ssl_exp_date>
    <ssl_amount>1.00</ssl_amount>
    <ssl_eci_ind>5</ssl_eci_ind>
    <ssl_3dsecure_value>MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=</ssl_3dsecure_value>
    <ssl_program_protocol>2</ssl_program_protocol>
    <ssl_dir_server_tran_id>abcdefg1234567890</ssl_dir_server_tran_id>
    <ssl_3ds_server_trans_id>12345abcdef6789</ssl_3ds_server_trans_id>
    <ssl_3ds_message_version>2.1.0</ssl_3ds_message_version>
    <ssl_3ds_trans_status>Y</ssl_3ds_trans_status>                                
    <ssl_3ds_trans_status_reason></ssl_3ds_trans_status_reason>
</txn>

Additional Information

Refer to our article on the Converge support siteLink opens new window to see a list of frequently asked questions and to learn more about 3D Secure.

Cash Advance

Apple Pay

3D Secure

Magento Guide