MasterPass

Converge offers MasterPass® as a digital wallet expansion for Hosted Payments Page and Checkout.js. MasterPass lets customers check out on a merchant's website using any MasterPass connected payment card.

Customers using MasterPass store and manage their payment and shipment information at the MasterPass website, when they are ready to purchase goods, their information will be securely shared with the merchant website. Converge uses the Elavon eMPI engine to allow processing of MasterPass wallet transactions.

The following transactions types are supported when processing MasterPass transactions:

Transaction Types Description
ccsale Credit Card Sale
ccauthonly Credit Card Auth Only

error_outline
note
  • The terminal must be setup under region Canada and market segment eCommerce.
  • The terminal must be setup for MasterPass.
  • All card types are supported under the MasterPass wallet.

The following information is supported for MasterPass transactions:

Field Name Req? Description
ssl_eWallet C The wallet identifier, valid values: MasterPass

Note: Required for XML API to indicate that the Cardholder has opted to pay using MasterPass.
ssl_eWallet_shipping N Wallet shipping option to indicate if the shipping address information used is retrieved from the MasterPass website or the merchant’s website. Default is N.

Valid values:
  • Y = Use the Shipping address stored in MasterPass
  • N = Use the Shipping address from the merchant website or payment form
ssl_product_string N Product string. This is the list of products purchased at the merchant website. All products will be displayed as line item on MasterPass site along with the total amount.

The product string have to be formatted as following: (Unit Price:: Quantity: Description: Image URL|) of the product, several products can be provided, each separated by “|”. Converge will send a generic product string if not provided.

Example:

10.00::1::shirt::https://merchantwebsite/shirtpic.gif |22.00::1::pants:: https://merchantwebsite/pantspic.gif |15.00::1::hat::https://merchantwebsite/hatpic.gif |5.00::1::socks::https://merchantwebsite/sockspic.gif
ssl_callback_url Y The url of the merchant that will host the response.
ssl_txn_auth_token Y This value must be passed a transactionToken as part of paymentData that must be sent as part of a Masterpass transaction.

Using Checkout.js

To use MasterPass with Checkout.js, you must take the following steps:

  1. Include Converge Checkout.js and render a MasterPass button on your page.

  2. Prepare a session token.

  3. Provide callback.

Transaction Example

Below is an example of an embeddable form for MasterPass. This form renders a MasterPass button, and presents a form to capture and pass the required information to requests a transaction token from MasterPass.

<!DOCTYPE HTML>
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <title>Embedded Payment Demo</title>
    <script src="jquery.js"></script>
    <script src="https://api.demo.convergepay.com/hosted-payments/Checkout.js"></script>
    <script>

        var transactionToken;

        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", "");
            }
        };

        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://api.demo.convergepay.com/hosted-payments/hosted-payments/transaction_token", tokenRequest, function( data ) {
                $("#token").html(data);
                transactionToken = data;
                initiateEwallets();
            });
            return false;
        }

        function initiateEwallets () {
            var paymentData = {
                ssl_txn_auth_token: transactionToken,
                ssl_callback_url: 'https://<your website>/checkout-js-merchantresponse.html?osessionId='+transactionToken
            };
            ConvergeEmbeddedPayment.initMasterPass('masterpass-button', 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;
        }
    </script>

  </head>
  <body>
        <form name="getSessionTokenForm">
            Converge Account Number: <input type="text" id="ssl_merchant_id" name="ssl_merchant_id" size="6" value="000006"> <br>
            API User ID: <input type="text" id="ssl_user_id" name="ssl_user_id" size="20" value="jin_api"> <br>
            API User Terminal Identifier: <input type="text" id="ssl_pin" name="ssl_pin" size="64" value="E3NC2X8Y4H8LRZ48TREF0FN551WXKHJS8OUWJLV1RQO5JA755TPR6H5K5K9NFRQD"> <br>
            Transaction Type: <input type="text" id="ssl_transaction_type" name="ssl_transaction_type" value="CCSALE"> <br>
            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>
        <br/><br/>
        <div id="masterpass-button"></div>
        <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>

Sample Callback Handler

This page includes the variables and functions to create a callback required for handling the response from a MasterPass session.

<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <title>Masterpass Response Demo</title>
    <%
        String osessionId = request.getParameter("osessionId");
        String oauth_verifier = request.getParameter("oauth_verifier");
        String mpstatus = request.getParameter("mpstatus");
        String cartId = request.getParameter("cartId");
    %>
    <script src="jquery.js"></script>
    <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));
            },
            onCancelled: function () {
                showResult("cancelled", "");
            }
        };  
        function payByMasterpass7() {
            var paymentData = {
                osessionId: $("#osessionId").val(),
                oauth_verifier: $("#oauth_verifier").val()
            };
            ConvergeEmbeddedPayment.payByMasterpass(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;
        }
    </script>

  </head>
  <body onload="payByMasterpass7()">
        osessionId: <input type="text" id="osessionId" size="20" value="<%=osessionId%>"> <br>
        oauth_verifier: <input type="text" id="oauth_verifier" size="20" value="<%=oauth_verifier%>"> <br>
        mpstatus: <input type="text" id="mpstatus" size="20" value="<%=mpstatus%>"> <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>