<p>Elavon downloads and stores cookies on your device when you visit our website. We use these cookies to better understand and improve your browsing experience by identifying most visited pages, personalising content, and measuring site performance.</p>


Essential cookies enable core functionality such as page navigation and access to secure areas. The website cannot function properly without these cookies; they can only be disabled by changing your browser preferences.

These are cookies that support site functionality that is visible or advantageous to you or your experience of the site, they enable websites to remember choices and provide a more personalized experience.   Functional cookies help to provide services that you request, such as language preference or layout.

Performance cookies help us to improve our website by collecting and reporting information on its usage (for example, which of our pages are most frequently visited).

These cookies and similar technologies gather information about your browsing habits. They remember that you've visited a website and share this information with other organisations, such as advertisers and platforms on which we advertise. They do this in order to provide you with ads that are more relevant to you and your interests. Although these cookies and similar technologies can track your visits to other websites, they don't usually know who you are. Without these cookies, online advertisements you encounter will be less relevant to you and your interests.

Cookie Settings

<p>U.S. Bank Europe DAC. Registered in Ireland – Number 418442..  Registered Office: Block F1, Cherrywood Business Park, Dublin 18, D18 W2X7, Ireland.</p>
<p>U.S. Bank Europe DAC, trading as Elavon Merchant Services, is regulated by the Central Bank of Ireland.</p>
<p><br>
U.S. Bank Europe DAC. Registered in Ireland with Companies Registration Office. The liability of the member is limited. United Kingdom branch registered in England and Wales under the number BR022122.</p>
<p>U.S. Bank Europe DAC, trading as Elavon Merchant Services, is a credit institution authorised and regulated by the Central Bank of Ireland.  Authorised by the Prudential Regulation Authority.  Subject to regulation by the Financial Conduct Authority and limited regulation by the Prudential Regulation Authority.  Details about the extent of our regulation by the Prudential Regulation Authority are available from us on request.</p>


Most popular solutions

Additional solutions

Fusebox integration & options

Optional platform features

Documentation

North America

Europe

Regions

EMV 3D Secure 2.0 or 3DS2 helps increase authorization rates by providing an additional layer of authentication that prevents unauthorized eCommerce transactions. The protocol helps protect merchant customers from CNP eCommerce-related chargeback fraud. 

3DS2 promotes frictionless cardholder authentication during the online checkout process and requests additional verification only when the card-issuing bank classifies a transaction as high-risk. It sends a large dataset about the cardholder and transaction to the card-issuing bank. This step provides the card-issuing bank with more insight into each transaction for authentication prior to transaction approval or decline. 
 
Fraud liability shifts from the merchant customer to the cardholder and card-issuing bank in the following conditions: 

- The issuer successfully authenticates the payment using EMV 3D Secure 2.0 protocols (e.g., in the authentication response, the issuer confirms the transaction as authenticated or attempted authentication). 
- The card is a Visa, MasterCard, Discover or American Express. 

**Requirements** 

All Converge integrators that want to use 3D Secure 2 must meet the following requirements. 

- 3D Secure 2 is enabled. Verify by calling :magic-link[/VirtualMerchantDemo/accountxml.do]{id="api-reference#tag/Terminal-Management"} with transaction type `terminalsetup`. 
- Region set to USA or Canada. 
- Market Segment set to Internet. 

## Step 1. Request a session token 

Request a session token :magic-link[/transaction_token]{id="api-reference#tag/Request-Session-Token"} using x-www-form-urlencoded key/value pairs. The session token response is only valid for 15 minutes and can only be used once. A session token will be returned.  

| Objects | Description |
|--------------|-----------------------|
| Credentials | API user credentials. :magic-link[Contact us]{id="overview#getting-started"} if you need your user credentials.<br>Required |
| Transaction type | Select `ccsale` |
| Transaction amount | Amount sent for sale |

## Step 2. Build your payment page

Your Checkout.js transaction request function must be able to: 

- Include the 3DS 2 Web SDK endpoint: 
  - Demo: `https://uat.libs.fraud.eu.elavonaws.com/sdk-web-js/1.2.0/3ds2-web-sdk.min.js` 
  - Production: `https://libs.fraud.elavongateway.com/sdk-web-js/1.2.0/3ds2-web-sdk.min.js` 
- Retrieve the session token response value.  
- Assign the session token response value to `ssl_txn_auth_token.`
- Retrieve the data from the :magic-link[payment form]{id="3d-secure-2#3d-secure-2-sample-code"}.
- Your function must include `ConvergeEmbeddedPayment.pay(paymentData, callback)` to enable your payment page to pass the collected data, process the transaction with Converge, and get the transaction response. 
   -  `paymentData` represents data that you include in the transaction request :magic-link[/hosted-payments/Checkout.js]{id="api-reference#tag/Checkout.js-Transaction-Request"}.
   -  `callback` accommodates the :magic-link[callback response]{id="take-a-payment#callback-transaction-response-sample"} variables for approved and declined requests. The callback function provides a JSON- formatted response. 
- Your function must also include `ConvergeEmbeddedPayment.getEFSToken(paymentData, callback)`
   - `paymentData` represents `ssl_txn_auth_token.`
   - `callback` accommodates the :magic-link[callback response]{id="take-a-payment#callback-transaction-response-sample"} variables for approved and declined requests. The callback function provides a JSON- formatted response. 

## 3D Secure 2 sample code 

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

```html
<!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.2.0/3ds2-web-sdk.min.js"; 
             } else { 
                srcEfs = "https://uat.libs.fraud.eu.elavonaws.com/sdk-web-js/1.2.0/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("SecureCredentials.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 getEFSCardholderName () {
            var firstName = $("#ssl_first_name").val();
            var lastName = $("#ssl_last_name").val();
            return firstName.concat(" ", lastName).substring(45);
        };
        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(), 
                cardholderName: getEFSCardholderName(),
                email:$("#ssl_email").val(),
                messageCategory : "01", 
                transType : "01", 
                threeDSRequestorAuthenticationInd : "01", 
                challengeWindowSize: "03", 
                clientStartProtocolVersion: "2.2.0", 
                clientEndProtocolVersion: "2.2.0", 
                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>
```