Session

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.

Hosted Session only works from version 18 of the API. However, versions 15, 16 and 17 are listed here. These versions must either be removed or hidden from the API Online Reference using an annotation in the code.

URL

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

Functions

attachToForm()

Hosts the selected sensitive card fields in an iFrame.

updateSession()

Stores the input from the hosted field into the session.

setFocus()

Sets focus on the specified hosted field.

setFocusStyle()

Sets the styling attributes for the specified hosted fields when the focus is gained.

Callbacks

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

<html>
<head>
    <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
    <script src="https://ap-gateway.mastercard.com/form/version/21/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>