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:
| 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.jsopen_in_newLink opens new window
3DS 2 Web SDK Production endpoint:https://libs.fraud.elavongateway.com/sdk-web-js/0.13.10/3ds2-web-sdk.min.jsopen_in_newLink 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 siteopen_in_newLink opens new window to see a list of frequently asked questions and to learn more about 3D Secure.