Masterpass™ Acceptance

How to add Masterpass as a payment option to your payment form.

MasterPass logo

Simplify Commerce makes it easy for you to add MasterPass as a payment option to your payment form. When you add MasterPass, your customers can choose to pay with any card registered in their MasterPass wallets.

Additionally, when you integrate with MasterPass using Simplify, you do not receive any of the customer's sensitive payment data. The card data is transferred between MasterPass and Simplify Commerce, and you will receive a single-use token that represents the payment information.

Overview

Adding MasterPass to your payments form is similar to tokenizing card details as described in the tutorial, so that payment form will be used as a basis for describing the steps involved.

When a customer clicks the MasterPass button, a new browser window will be opened. The customer will complete the MasterPass login and payment selection in this new window. Upon completion (or cancellation), the MasterPass results are sent to Simplify. Simplify then generates a single-use payment token, closes the window, and invokes a callback function on your page with the token contents.

Include Simplify.js

First you must include simplify.js in your page. If you are already performing tokenization of card details, your page will already have the required library included. jQuery is also required for these particular examples, but is not strictly required by simplify.js.

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script type="text/javascript" src="https://www.simplify.com/commerce/v1/simplify.js"></script>

Add the Buy with MasterPass button to your form

You can add the MasterPass button anywhere on your page. First, create a div where you want the button to go. The div must have a unique ID attribute. In the example below, we've added a div at the end of our form with an ID of buy-with-masterpass-div.

<form id="simplify-payment-form" action="" method="POST">
    <div>
        <label>Credit Card Number: </label>
        <input id="cc-number" type="text" maxlength="20" autocomplete="off" value="" autofocus />
    </div>
    <div>
        <label>CVC: </label>
        <input id="cc-cvc" type="text" maxlength="4" autocomplete="off" value=""/>
    </div>
    <div>
        <label>Expiry Date: </label>
        <select id="cc-exp-month">
            <option value="01">Jan</option>
            <option value="02">Feb</option>
            <option value="03">Mar</option>
            <option value="04">Apr</option>
            <option value="05">May</option>
            <option value="06">Jun</option>
            <option value="07">Jul</option>
            <option value="08">Aug</option>
            <option value="09">Sep</option>
            <option value="10">Oct</option>
            <option value="11">Nov</option>
            <option value="12">Dec</option>
        </select>
        <select id="cc-exp-year">
            <option value="13">2013</option>
            <option value="14">2014</option>
            <option value="15">2015</option>
            <option value="16">2016</option>
            <option value="17">2017</option>
            <option value="18">2018</option>
            <option value="19">2019</option>
            <option value="20">2020</option>
            <option value="21">2021</option>
            <option value="22">2022</option>
        </select>
    </div>
    <button id="process-payment-btn" type="submit">Process Payment</button>
    <div id="buy-with-masterpass-div"></div>
</form>

Next, you'll use the simplify.js library to add the MasterPass button to the div you created once your page loads. In this example, we update the script used in the payment form tutorial and add the button to our form.

$(document).ready(function() {
    $("#simplify-payment-form").on("submit", function() {
        // Disable the submit button
        $("#process-payment-btn").attr("disabled", "disabled");
        // Generate a card token & handle the response
        SimplifyCommerce.generateToken({
            key: "YOUR_PUBLIC_KEY",
            card: {
                number: $("#cc-number").val(),
                cvc: $("#cc-cvc").val(),
                expMonth: $("#cc-exp-month").val(),
                expYear: $("#cc-exp-year").val()
            }
        }, simplifyResponseHandler);

        // Prevent the form from submitting
        return false;
    });

    SimplifyCommerce.addMasterPassCheckoutButton("buy-with-masterpass-div", "YOUR_PUBLIC_KEY", masterPassResponseHandler,
        masterPassCanceledHandler);
});

Notice the call to SimplifyCommerce.addMasterPassCheckoutButton, which adds the MasterPass button to your div. It takes four arguments:

  • ID of the div in which you want to place the button.
  • Your public API key.
  • Reference to a function to handle the MasterPass response (success or failure).
  • Reference to a function to handle the case when the customer cancels the action.

This is the button that will be added to your page.

Buy with MasterPass

TESTING: During testing and integration, you will be sent to the sandbox MasterPass environment. You can login to the sandbox MasterPass Wallet using the credentials: User: masterpass@simplify.com Password: abcd1234 and Security Code: 123456. The default card ending in 0014 can be used for approval in Simplify Commerce. All other cards will decline in sandbox mode.

Handle the MasterPass response

You will need to create two functions to handle the responses from simplify.js. The first will handle the response from Simplify Commerce containing the single-use token or error if there was some failure, and the second will be invoked if your customer cancels the MasterPass payment selection.

Handle single-use token response

When the customer selects a card for payment from MasterPass, Simplify Commerce will create a single-use token and invoke this callback function with the response. If there are errors with the token creation, the function will be invoked with the error details. You can handle the response in several ways. Here, we show two examples.

Example 1

In this example, we handle the response exactly as in the payment form tutorial. The callback function takes two arguments, which are the same arguments as in the other tutorial. We check the response for errors and display them if they exist. Upon a successful response, the token is added to the form, and the form is submitted to your server.

function masterPassResponseHandler(data, status) {
    var $paymentForm = $("#simplify-payment-form");
    // Remove all previous errors
    $(".error").remove();
    // Check for errors
    if (data.error) {
        // Show any validation errors
        if (data.error.code == "validation") {
            var fieldErrors = data.error.fieldErrors,
                fieldErrorsLength = fieldErrors.length,
                errorList = "";
            for (var i = 0; i < fieldErrorsLength; i++) {
                errorList += "<div class='error'>Field: '" + fieldErrors[i].field +
                             "' is invalid - " + fieldErrors[i].message + "</div>";
            }
            // Display the errors
            $paymentForm.after(errorList);
        }

    } else {
        // The token contains id, last4, and card type

        var token = data.cardToken["id"];

        // Insert the token into the form so it gets submitted to the server
        $paymentForm.append("<input type='hidden' name='simplifyToken' value='" + token + "' />");
        // Submit the form to the server
        $paymentForm.get(0).submit();
    }
}

Example 2

Instead of automatically submitting the form as in the previous example, you may also choose to display the results of the MasterPass selection to allow the customer to confirm before submitting the form. In this case, you could populate the form with the card last four digits to show the customer the card that was selected. You might also choose here to hide other form elements, like the expiration and CVC fields, or you may choose to display some message prompting the customer to review the payment details before submitting the form. This example shows how it might look.

function masterPassResponseHandler(data, status) {
    var $paymentForm = $("#simplify-payment-form");
    // Remove all previous errors
    $(".error").remove();
    // Check for errors
    if (data.error) {
        // Show any validation errors
        if (data.error.code == "validation") {
            var fieldErrors = data.error.fieldErrors,
                fieldErrorsLength = fieldErrors.length,
                errorList = "";
            for (var i = 0; i < fieldErrorsLength; i++) {
                errorList += "<div class='error'>Field: '" + fieldErrors[i].field +
                             "' is invalid - " + fieldErrors[i].message + "</div>";
            }
            // Display the errors
            $paymentForm.after(errorList);
        }

    } else {
        // The token contains id, last4, and card type

        var token = data.cardToken["id"];

        // Insert the token into the form so it gets submitted to the server
        $paymentForm.append("<input type='hidden' name='simplifyToken' value='" + token + "' />");
        // Submit the form to the server
        $("#cc-number").val("XXXX-XXXX-XXXX-" + data.cardToken.card.last4);
        $("#cc-number").prop('disabled', true);

        $paymentForm.after("<div class='confirmation'>Please confirm your payment details before submitting</div>");
    }
}

Handle the cancellation response

Next you will create a function that will be invoked if your customer cancels the MasterPass payment selection. You should note that if your customer manually closes the MasterPass window, this function will not be invoked. In this example, we take no action, simply logging something to the console.

function masterPassCanceledHandler () {
    console.log ("MasterPass canceled")
}

Completing the payment

Once the form is submitted to your server with the token, you must call the Simplify Commerce API from your server to complete the payment. This is performed exactly as described in the Charging a Card section in the payment form tutorial.

PaymentsApi.PUBLIC_KEY = "YOUR_PUBLIC_API_KEY";
PaymentsApi.PRIVATE_KEY = "YOUR_PRIVATE_API_KEY";

Payment payment = Payment.create(new PaymentsMap()
        .set("amount", 1000)
        .set("currency", "USD")
        .set("description", "payment description")
        .set("reference", "7a6ef6be31")
        .set("token", "[TOKEN ID]")
);

if ("APPROVED".equals(payment.get("paymentStatus"))) {
    System.out.println("Payment approved");
}
require 'simplify'

Simplify::public_key = "YOUR_PUBLIC_API_KEY"
Simplify::private_key = "YOUR_PRIVATE_API_KEY"

payment = Simplify::Payment.create({
        "amount" => "1000",
        "token" => "[TOKEN ID]",
        "description" => "payment description",
        "reference" => "7a6ef6be31",
        "currency" => "USD"
})

if payment['paymentStatus'] == 'APPROVED'
    puts "Payment approved"
end
import simplify

simplify.public_key = "YOUR_PUBLIC_API_KEY"
simplify.private_key = "YOUR_PRIVATE_API_KEY"

payment = simplify.Payment.create({
        "amount" : "1000",
        "token" : "[TOKEN ID]",
        "description" : "payment description",
        "reference" : "7a6ef6be31",
        "currency" : "USD"

})

if payment.paymentStatus == 'APPROVED':
    print "Payment approved"
<?php

require_once("./lib/Simplify.php");

Simplify::$publicKey = 'YOUR_PUBLIC_API_KEY';
Simplify::$privateKey = 'YOUR_PRIVATE_API_KEY';

$payment = Simplify_Payment::createPayment(array(
        'amount' => '1000',
        'token' => '[TOKEN ID]',
        'description' => 'payment description',
        'reference' => '7a6ef6be31',
        'currency' => 'USD'
));

if ($payment->paymentStatus == 'APPROVED') {
    echo "Payment approved\n";
}

?>
use Net::Simplify;

$Net::Simplify::public_key = "YOUR_PUBLIC_API_KEY";
$Net::Simplify::private_key = "YOUR_PRIVATE_API_KEY";

my $payment = Net::Simplify::Payment->create({
    amount => "1000",
    token => "[TOKEN ID]",
    description => "payment description",
    reference => "7a6ef6be31",
    currency => "USD"
});

print "Payment status ", $payment->{paymentStatus}, "\n";
using SimplifyCommerce.Payments;

PaymentsApi.PublicApiKey = "YOUR_PUBLIC_KEY";
PaymentsApi.PrivateApiKey = "YOUR_PRIVATE_KEY";

PaymentsApi api = new PaymentsApi();

Payment payment = new Payment();
payment.Amount = 1000;
payment.Currency = "USD";
payment.Description = "payment description";
payment.Reference = "7a6ef6be31";
payment.Token = "[TOKEN ID]";

try
{
    payment = (Payment)api.Create(payment);
}
catch (Exception e)
{
    Console.WriteLine(e.ToString());
}
var Simplify = require("simplify-commerce"),
    client = Simplify.getClient({
        publicKey: 'YOUR_PUBLIC_API_KEY',
        privateKey: 'YOUR_PRIVATE_API_KEY'
    });

client.payment.create({
    amount : "1000",
    token : "[TOKEN ID]",
    description : "payment description",
    reference : "7a6ef6be31",
    currency : "USD"
}, function(errData, data){

    if(errData){
        console.error("Error Message: " + errData.data.error.message);
        // handle the error
        return;
    }

    console.log("Payment Status: " + data.paymentStatus);
});

The example above charges $10 USD using the card associated with the card token you created in the payments form. You must supply your API Keys (for either Sandbox or Live mode).