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

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

• Electronic Check

  • Sale - ecspurchase
  • Add Installment - ecsaddrecurring

• Gift Card

  • Sale - egcsale

Checkout.js and Digital wallets

Checkout.js can support the following converge digital wallet options:

• Apple Pay
• Google Pay
• Click to Pay
• PayPal

Checkout.js Integration

To integrate using Checkout.js, you will need to complete the following steps:

1. Contact the Software Technical Support Team or Customer Service.
2. 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:

1. Request a Session Token
2. POST a Transaction Request
3. Print a Transaction Response

Session Token Request

Your session token request function must include the following parameters:

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.

POST Transaction Request

Your POST transaction request function must include these 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.
• 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>

• previousIntegration Methods
• nextCheckout.js Methods and Parameters