Session SDK Overview

The session.js JavaScript library allows you to collect sensitive payment details from the payer in fields hosted by the gateway. Use this library if you want to control the layout and styling of your payment page, while reducing PCI compliance costs. The gateway collects the payment details from the payer and stores them in a payment session. You can then include the payment session in place of the payment details in the transaction request to process a payment. For full details see Implementing a Hosted Session Integration. The library also has support for collecting multiple sets of payment details on the same payment page, see Multiple Hosted Session for details.

Supported only in DirectAPI version 18 and later.

URL Copied to clipboard

https://test-gateway.mastercard.com/form/version/18/merchant/<MERCHANTID>/session.js

Functions Copied to clipboard

attachToForm()

Hosts the selected sensitive card fields in an iFrame.

updateSession()

Stores the input from the hosted field into the session.

Callbacks Copied to clipboard

onFocus

Invoked when the hosted field has gained focus.

onBlur

Invoked when the hosted field has lost focus.

onChange

Invoked when the input value in the hosted field has changed.

Example Copied to clipboard 

<html>
<head>
    <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
    <script src="https://test-gateway.mastercard.com/form/version/18/merchant/<MERCHANTID>/session.js"></script>
</head>
<body>

<!-- CREATE THE HTML FOR THE PAYMENT PAGE -->

<div>Please enter your payment details:</div>
<div>Card Number: <input type="text" id="card-number" class="input-field" value="" readonly></div>
<div>Expiry Month:<input type="text" id="expiry-month" class="input-field" value=""></div>
<div>Expiry Year:<input type="text" id="expiry-year" class="input-field" value=""></div>
<div>Security Code:<input type="text" id="security-code" class="input-field" value="" readonly></div>
<div><button id="payButton" onclick="pay();">Pay Now</button></div>

// ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE

PaymentSession.attachToForm({
fields: {
    cardNumber: "#card-number",
    securityCode: "#security-code",
    expiryMonth: "#expiry-month",
    expiryYear: "#expiry-year"
},
frameEmbeddingMitigation: ["javascript", "x-frame-options", "csp"]
}, function (response) {
    // HANDLE RESPONSE FROM ATTACH TO FORM
    if ("ok" == response) {
        console.log("Session created or validated.");
        // SET THE FOCUS STYLE ON A FIELD AND SET ITS FOCUS
        PaymentSession.setFocusStyle(["cardNumber"], {backgroundColor: 'green'});
        PaymentSession.setFocus("cardNumber");
    } else {
        console.log("Failed to create or validate session:" + response);
    }
})

function pay() {
    // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS

    PaymentSession.updateSession(function (response) {
        // HANDLE RESPONSE FOR UPDATE SESSION
        if (response.status) {
            if ("ok" == response.status) {
                console.log("Session updated with data: " + response.session.id);
                // PERFORM AN AUTHENTICATED PAY USING THE SESSION ID
            } else if ("fields_in_error" == response.status)  {

                console.log("Session update failed with field errors.");
                if (response.errors.cardNumber) {
                    console.log("Card number invalid or missing.");
                }
                if (response.errors.expiryYear) {
                    console.log("Expiry year invalid or missing.");
                }
                if (response.errors.expiryMonth) {
                    console.log("Expiry month invalid or missing.");
                }
                if (response.errors.securityCode) {
                    console.log("Security invalid or missing.");
                }
            } else if ("request_timeout" == response.status)  {
                console.log("Session update failed with request timeout: " + response.errors.message);
            } else if ("system_error" == response.status)  {
                console.log("Session update failed with system error: " + response.errors.message);
            }
        } else {
            console.log("Session update failed: " + response);
        }
    });
}
</script>
</body>
</html>