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.

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

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. Not further steps apart from 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. Not further steps apart from 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. Not further steps apart from 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. Not further steps apart from those listed under General Requirements are necessary.

Checkout.js

Initiate the Checkout.js Session

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

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";      
            if ($("#env").val() === 'PROD'){
                efsEnv = "prod";
            } else {
                efsEnv = "dev";
            }
            var srcEfs = "https://" + efsEnv + ".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_merchant_id: $("#ssl_merchant_id").val(),
                ssl_user_id: $("#ssl_user_id").val(),
                ssl_pin: $("#ssl_pin").val(),
                ssl_transaction_type: $("#ssl_transaction_type").val(),
                ssl_amount: $("#ssl_amount").val()
            };

            $.post("https://" + envs[$("#env").val()] + "/hosted-payments/transaction_token", 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()
            };
            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 === '02' || eci === '05'){
            return '5';
        } else if (eci === '01' || eci === '06'){
            return '6';
        } else {
            return '7';
        }
    };

        function handleAllInOne() {
        var sdk = new window.Elavon3DSWebSDK({ baseUrl : 'https://uat.gw.fraud.eu.elavonaws.com/3ds2', 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"
        };
        console.log(request);

        sdk.web3dsFlow(request).then( function success(response) {
            console.log(response);
            document.getElementById('ssl_dir_server_tran_id').value = response.dsTransID;
            document.getElementById('ssl_eci_ind').value = getEFSEci(response.eci);
            if (response.authenticationValue) {
                document.getElementById('ssl_3dsecure_value').value = response.authenticationValue;
            }
            document.getElementById('ssl_program_protocol').value = 2;          
        }, 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">
            Converge Account Number: <input type="text" id="ssl_merchant_id" name="ssl_merchant_id" value=""> <br>
            API User ID: <input type="text" id="ssl_user_id" name="ssl_user_id" size="20" value=""> <br>
            API User Terminal Identifier: <input type="text" id="ssl_pin" name="ssl_pin" size="64" value=""> <br>
            Transaction Type: <select id="ssl_transaction_type" name="ssl_transaction_type">
                    <option value="CCSALE">Credit Card Sale</option>
                    <option value="CCAUTHONLY">Credit Card Authorization Only</option>
                    <option value="CCGETTOKEN">Get a Token</option>
                </select><br>
            Transaction Amount: <input type="text" id="ssl_amount" name="ssl_amount" value=""> <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/>
            CAVV: <input id="ssl_3dsecure_value" type="text" name="ssl_3dsecure_value" 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>
Get the EFS Token with

XML API

Get EFS Token

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

<txn>
    <ssl_merchant_ID>VID</ssl_merchant_ID>
    <ssl_user_id>UID</ssl_user_id>
    <ssl_pin>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() {
    var sdk = new window.Elavon3DSWebSDK({ baseUrl : 'https://uat.gw.fraud.eu.elavonaws.com/3ds2', 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"
};
console.log(request);
sdk.web3dsFlow(request).then( function success(response) {
    console.log(response);
    document.getElementById('ssl_dir_server_tran_id').value = response.dsTransID;
    document.getElementById('ssl_eci_ind').value = getEFSEci(response.eci);
    if (response.authenticationValue) {
        document.getElementById('ssl_3dsecure_value').value = response.authenticationValue;
    }
    document.getElementById('ssl_program_protocol').value = 2;          
}, 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>VID</ssl_merchant_ID>
    <ssl_user_id>UID</ssl_user_id>
    <ssl_pin>PIN</ssl_pin>
    <ssl_transaction_type>ccsale</ssl_transaction_type>
    <ssl_card_number>5000300020003003</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>
</txn>