Checkout.js
Checkout.js integration enables your eCommerce store to use Converge to collect customer data and process payments securely. This integration method is ideal for businesses that want:
- Full control over the customization of their payment page.
- A consistent look and feel throughout their website and payment page.
- To use functional calls to submit transactions to Converge from the web browser of their customers.
Checkout.js is Converge’s JavaScript library used to collect cardholder data from the customer’s browser and send it directly to Converge for Processing. Sensitive data won’t touch the Merchant’s server allowing merchants to avoid the compliance burden for handling payment card information or personally identifying data. The result of the transaction returns to the browser and can display as a response to the customer and update the back end systems.
Requirements
To use the Converge JavaScript Library, your server must have the following settings:
- All pages that use the Converge Payment Script must use HTTPS protocol.
- The domain must have a valid SSL certificate.
- The server must support TLS 1.2 protocol.
This list provides an overview of the Checkout.js integration method:
- Ease of Integration: Medium
- Service Provider PCI: PCI Level 1
- Merchant PCI DSS Self-Assessment Questionnaire (SAQ) Type: SAQ A - EP
- Customization: Extensive
- Most Suited for These Market Segments:
- eCommerce
important
PCI requirements for Integrated Partners:
- If a partner has access to payment card data, one is required to validate PCI compliance as a PCI Level 1 Service Provider annually. This requires the submission of a Report on Compliance (ROC) based on an on-site audit completed by a Qualified Security Assessor (QSA) before processing.
- Subsequently, Card Brand registration is also required. PCI validation must be completed and documentation provided in order to execute the registration process with each card brand network annually.
Payment and Transaction Types
This section provides an overview of the transaction types that the Checkout.js integration option supports for the following payment types:
Credit Card
- Sale -
ccsale
- Authorization Only -
ccauthonly
- Verification -
ccverify
- Add Recurring -
ccaddrecurring
- Add Installment -
ccaddinstall
- Get Token -
ccgettoken
- Sale -
Electronic Check
- Sale -
ecspurchase
- Add Installment -
ecsaddrecurring
- Sale -
Gift Card
- Sale -
egcsale
- Sale -
Checkout.js and Digital wallets
Checkout.js can support the following converge digital wallet options:
Checkout.js Integration
To integrate using Checkout.js, you will need to complete the following steps:
- Contact the Software Technical Support Team or Customer Service.
- Develop your payment processing program.
Contact Software Technical Support Team
To integrate using Checkout.js, you will need to contact the Software Technical Support Team or Customer Service at 1-800-377-3962 | Option 2 | Option 2 to:
- Register and add the IP address of the server that will send the session token request and the Web URL to an allowed list.
- Set a Converge User ID with a Hosted Payment API User status with permission to post a session token request.
- Associate the Converge User ID with the eCommerce terminal.
Develop the Payment Processing Program
Your Payment Processing program must include functions for the following:
- Request a Session Token
- POST a Transaction Request
- Print a Transaction Response
Session Token Request
Your session token request function must include the following parameters:
Field name | Description | Required | Length | Data type |
---|---|---|---|---|
ssl_merchant_id | Merchant ID Elavon-assigned Converge account ID. | Required | 15 | numeric |
ssl_user_id | Converge User ID The user ID with Hosted Payment API User status that can send transaction requests through the terminal. | Required | 15 | alphanumeric |
ssl_pin | Terminal ID Unique identifier of the terminal that will process the transaction request and submit to the Converge gateway. Important: The ssl_user_id sending the transaction request must be associated with the terminal that will process the request. | Required | 64 | alphanumeric |
ssl_transaction_type | Transaction Type For the complete list of payment and transaction types supported by Checkout.js, refer to Payment and Transaction Types. | Required | 20 | alphanumeric |
ssl_amount | Transaction Amount Data entry depends on the ssl_transaction_type value. | Conditional | 11 | numeric |
The endpoints to POST the session token request to are as follows:
- Demo Site:
https://api.demo.convergepay.com/hosted-payments/transaction_token
- Live Site:
https://api.convergepay.com/hosted-payments/transaction_token
Your session token request function must be able to:
- Capture the Session Token Response from Converge.
- Redirect the customer browser’s to your custom payment form or page.
note
The Session Token Response is only valid for 15 minutes and can only be used once.
POST Transaction Request
Your POST transaction request function must include these parameters:
Field name | Description | Required | Length | Data type |
---|---|---|---|---|
ssl_txn_auth_token | Session Token Response | Required | 50 | alphanumeric |
[Card Data] | The card data parameters will depend on the transaction type. Refer to the Transaction Types section to determine the appropriate Card Data parameters. | |||
[Transaction Data] | The transaction data parameters will depend on the transaction type. Refer to the Transaction Types section to determine the appropriate Transaction Data parameters. |
Your POST transaction request function must be able to:
- Retrieve the Session Token Response value.
- Assign the Session Token Response value to
ssl_txn_auth_token
. - Retrieve the data from the Payment Form.
- Your function must also 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 the card data and transaction data that you include in the transaction request.
- Your function must also include
- Accommodate the callback response variables for approved and declined requests. The callback function provides a JSON- formatted response.
The endpoints to POST the transaction request to are:
- Demo Site:
https://api.demo.convergepay.com/hosted-payments/Checkout.js
- Live Site:
https://api.convergepay.com/hosted-payments/Checkout.js
Print Transaction Response
A JSON-formatted response will be provided to Callback functions. You can use information from the response to populate messages to the shopper and update backend records.
Sample Code
Sample Transaction Form
This is an example implementation of a Checkout.js payment form. This script will call for a session token and then display the payment modal.
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Checkout.js Demo</title>
<script src="https://api.demo.convergepay.com/hosted-payments/Checkout.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
<script>
function initiateCheckoutJS() {
var tokenRequest = {
ssl_amount: document.getElementById('ssl_amount').value
};
$.post("checkoutjscurlrequestdevportal.php", tokenRequest, function (data) {
document.getElementById('token').value = data;
transactionToken = data;
});
return false;
}
function pay() {
var token = document.getElementById('token').value;
var card = document.getElementById('card').value;
var exp = document.getElementById('exp').value;
var cvv = document.getElementById('cvv').value;
var gettoken = document.getElementById('gettoken').value;
var addtoken = document.getElementById('addtoken').value;
var firstname = document.getElementById('name').value;
var lastname = document.getElementById('lastname').value;
var merchanttxnid = document.getElementById('merchanttxnid').value;
var paymentData = {
ssl_txn_auth_token: token,
ssl_card_number: card,
ssl_exp_date: exp,
ssl_get_token: gettoken,
ssl_add_token: addtoken,
ssl_first_name: firstname,
ssl_last_name: lastname,
ssl_cvv2cvc2: cvv,
ssl_merchant_txn_id: merchanttxnid
};
var callback = {
onError: function (error) {
showResult("error", error);
},
onDeclined: function (response) {
console.log("Result Message=" + response['ssl_result_message']);
showResult("declined", JSON.stringify(response));
},
onApproval: function (response) {
console.log("Approval Code=" + response['ssl_approval_code']);
showResult("approval", JSON.stringify(response));
}
};
ConvergeEmbeddedPayment.pay(paymentData, callback);
return false;
}
function showResult(status, msg) {
document.getElementById('txn_status').innerHTML = "<b>" + status + "</b>";
document.getElementById('txn_response').innerHTML = msg;
}
</script>
</head>
<body>
<br>
First Name: <input type="text" id="name" name="ssl_first_name" size="25" value="John"> <br><br>
Last Name: <input type="text" id="lastname" name="ssl_last_name" size="25" value="Smith"> <br><br>
Transaction Amount: <input type="text" id="ssl_amount" name="ssl_amount" value="25.00"> <br> <br>
<button onclick="return initiateCheckoutJS();">Click to Confirm Order</button> <br>
<br>
<br>
<br>
<br>
Transaction Token: <input id="token" type="text" name="token"> <br />
Card Number: <input id="card" type="text" name="card" value="4124939999999990" /> <br />
Expiry Date: <input id="exp" type="text" name="exp" value="1222" /> <br />
CVV2: <input id="cvv" type="text" name="cvv" value="123"> <br />
Merchant TXN ID: <input id="merchanttxnid" type="text" name="merchanttxnid" value="MerchantTXNIDHere" /> <br />
<input id="gettoken" type="hidden" name="gettoken" value="y" />
<input id="addtoken" type="hidden" name="addtoken" value="y" />
<button onclick="return pay();">Process Payment</button>
<br>
<br>
<br>
<br>
Transaction Status:<div id="txn_status"></div>
<br>
Transaction Response:<div id="txn_response"></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 = "convergeapi"; //Converge User ID *MUST FLAG AS HOSTED API USER IN CONVERGE UI*
$merchantPIN = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; //Converge PIN (64 CHAR A/N)
$url = "https://api.demo.convergepay.com/hosted-payments/transaction_token"; // URL to Converge demo session token server
//$url = "https://api.convergepay.com/hosted-payments/transaction_token"; // URL to Converge production session token server
// Read the following querystring variables
$firstname=$_POST['ssl_first_name']; //Post first name
$lastname=$_POST['ssl_last_name']; //Post last name
$amount= $_POST['ssl_amount']; //Post Tran Amount
$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=$merchantPIN".
"&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);
// curl_setopt($ch, CURLOPT_PROXY, "http://your.proxy.server:port"); // proxy server config
$result = curl_exec($ch); // run the curl process
curl_close($ch); // Close cURL
echo $result; //shows the session token.
?>
Sample Response
"ssl_card_number": "34**********1117", "ssl_transaction_type": "SALE", "ssl_result": "1", "ssl_txn_id": "031118MB-7E2DFD65-8317-45BD-A329-2501279FA0B5", "ssl_avs_response": " ", "ssl_approval_code": " ", "ssl_amount": "1.00", "cust_checkbox": "off", "ssl_txn_time": "11/03/2018 06:44:47 PM", "ssl_account_balance": "0.00", "ssl_exp_date": "1222", "ssl_result_message": "APPROVED", "ssl_card_short_description": "AMEX", "ssl_card_type": "CREDITCARD"
Sample Dynamic Currency Converter
This form includes the Dynamic Currency Conversion option for Checkout.js:
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Embedded Payment DCC Demo</title>
<script src="https://api.demo.convergepay.com/hosted-payments/Checkout.js"></script>
<script>
var callback = {
onError: function (error) {
showResult("error", error);
},
onDeclined: function (response) {
showResult("declined", JSON.stringify(response));
},
onApproval: function (response) {
showResult("approval", JSON.stringify(response));
},
onDCCDecision: function (response) {
document.getElementById('ssl_conversion_rate').value = response.ssl_conversion_rate;
showResult("DCC decision", JSON.stringify(response));
}
};
function showResult (status, msg) {
document.getElementById('txn_status').innerHTML = "<b>" + status + "</b>";
document.getElementById('txn_response').innerHTML = msg;
}
function pay () {
var token = document.getElementById('token').value;
var card = document.getElementById('card').value;
var exp = document.getElementById('exp').value;
var cvv = document.getElementById('cvv').value;
var paymentData = {
ssl_txn_auth_token: token,
ssl_card_number: card,
ssl_exp_date: exp,
ssl_cvv2cvc2: cvv
};
ConvergeEmbeddedPayment.pay(paymentData, callback);
return false;
}
function dcc (option) {
ConvergeEmbeddedPayment.dccDecision(option, callback);
return false;
}
</script>
</head>
<body>
<form id="firstForm">
Transaction Token: <input id="token" type="text" name="token"> <br/>
Card Number: <input id="card" type="text" name="card" > <br/>
Expiry Date: <input id="exp" type="text" name="exp" > <br/>
CVV2: <input id="cvv" type="text" name="cvv"> <br/>
<button onclick="return pay();">Pay</button>
</form>
<br>
<form id="secondForm">
Converion Rate: <input id="ssl_conversion_rate" type="text"> <br/>
<button onclick="return dcc(true);">Pay with cardholder currency</button><br>
<button onclick="return dcc(false);">Pay with transaction currency</button><br>
</form>
<br>
Transaction Status:<div id="txn_status"></div>
<br>
Transaction Response:<div id="txn_response"></div>
</body>
</html>
Sample 3D Secure Form
This form includes the 3D Secure function for Checkout.js:
<!DOCTYPE HTML>
<html>
<head>
<script src="https://api.convergepay.com/hosted-payments/Checkout.js"></script>
<script>
function threeDSecureReturn () {
var md = document.getElementById('md').value;
var pares = document.getElementById('pares').value;
var callback = {
onError: function (error) {
showResult("error", error);
},
onDeclined: function (response) {
showResult("declined", JSON.stringify(response));
},
onApproval: function (response) {
showResult("approval", JSON.stringify(response));
}
};
ConvergeEmbeddedPayment.threeDSecureReturn(md, pares, callback);
return false;
}
function showResult (status, msg) {
document.getElementById('txn_status').innerHTML = "<b>" + status + "</b>";
document.getElementById('txn_response').innerHTML = msg;
}
</script>
</head>
<body>
<form id="firstForm">
PaRes: <input id="pares" type="text" name="pares"> <br/>
MD: <input id="md" type="text" name="md"> <br/>
<button onclick="return threeDSecureReturn();">Continue</button>
</form>
<br>
Transaction Status:<div id="txn_status"></div>
<br>
Transaction Response:<div id="txn_response"></div>
</body>
</html>
Sample Surcharge Form
This form includes the Surcharge function for Checkout.js:
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Surcharge Test Script Demo</title>
<script src="https://code.jquery.com/jquery-3.5.1.js"> </script>
<script src="https://demo.convergepay.com/hosted-payments/Checkout.js"></script>
<script>
function initiateCheckoutJS() {
var tokenRequest = {};
$.post("checkoutjscurlrequestdevportal.php", tokenRequest, function (data) {
document.getElementById('ssl_txn_auth_token').value = data;
transactionToken = data;
});
return false;
}
var callback = {
onError: function (error) {
showResult("error", error);
},
onDeclined: function (response) {
//Transaction will run as regular sale if not elligable for Surcharge.
if (response.surchargeAllowed === 'Y') {
document.getElementById('creditSurchargeForm').style.display = "block";
showResult("credit surcharge", JSON.stringify(response));
} else {
showResult("declined", JSON.stringify(response));
}
},
onApproval: function (response) {
showResult("approval", JSON.stringify(response));
},
onCancelled: function () {
showResult("cancelled", "");
}
};
function payWithCreditCard() {
var paymentData = {
ssl_txn_auth_token: $('#ssl_txn_auth_token').val(),
ssl_card_number: $("#ssl_card_number").val(),
ssl_exp_date: $("#ssl_exp_date").val(),
ssl_cvv2cvc2: $("#ssl_cvv2cvc2").val(),
ssl_amount: $("#ssl_amount").val(),
ssl_avs_address: $("#ssl_avs_address").val(),
ssl_avs_zip: $("#ssl_avs_zip").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;
document.getElementById('txn_hash').innerHTML = hash;
}
function creditSurcharge(option) {
ConvergeEmbeddedPayment.creditSurchargeDecision(option, callback);
if(option === false){
showResult("Cancelled", "Cardholder declined agreement.");
}
return false;
}
</script>
</head>
<body>
<br>
Transaction Token: <input type="text" id="ssl_txn_auth_token" name="ssl_txn_auth_token" size="38"><button
onclick="initiateCheckoutJS();">Get Session Token</button><br><br>
<form name="creditCardForm">
Amount: <input id="ssl_amount" type="text" name="ssl_amount" size="10" value="1.00"> <br>
Card Number: <input id="ssl_card_number" type="text" name="ssl_card_number" size="21" value="4159288888888882"> <br>
Expiry Date: <input id="ssl_exp_date" type="text" name="ssl_exp_date" size="10" value="1222"> <br>
CVV2: <input id="ssl_cvv2cvc2" type="text" name="ssl_cvv2cvc2" size="8" value="123"> <br>
AVS: <input id="ssl_avs_address" type="text" name="ssl_avs_address" size="12" value="1 Test St"> <br>
AVS ZIP: <input id="ssl_avs_zip" type="text" name="ssl_avs_zip" size="8" value="36320"> <br>
EMAIL: <input id="ssl_email>" type="text" name="ssl_email>" size="25" value="test@test.com"> <br>
<button onclick="return payWithCreditCard();">Pay With Credit Card</button>
</form>
<form name="creditSurchargeAccept" id="creditSurchargeForm" style="display:none">
<P> Accept Credit Surcharge: <br>
<button onclick="return creditSurcharge(true);">Yes</button>
<button onclick="return creditSurcharge(false);">No</button>
</form>
<br>
<hr><br>
Transaction Status:<div id="txn_status"></div>
<br>
Transaction Response:<div id="txn_response"></div>
<br>
Transaction Hash Value:<div id="txn_hash"></div>
</body>
</html>