Customizing the Hosted Fields
If you are using the Hosted Session integration method, you have various ways of customizing the hosted payment fields on your payment page. The customizations can help you match the look and feel of your payment page and improve your web site accessibility.
Styling hosted fields
You can style hosted payment fields to match the look and feel of your overall payment page.
setFocus( ): Sets focus on the specified hosted field.setFocusStyle( ): Sets the styling attributes for the specified hosted fields when they gain focus.setHoverStyle( ): Sets the styling attributes for the specified hosted fields when a mouse hover occurs over them.setPlaceholderStyle( ): Sets the styling attributes for the placeholder text displayed on the specified hosted fields before the payer replaces it with their own entry.setPlaceholderShownStyle( ): Sets the styling attributes for the specified hosted fields when the placeholder text is visible.
Payment field styling example
PaymentSession.setFocus('card.number');
PaymentSession.setFocusStyle(["card.number","card.securityCode"], {
borderColor: 'red',
borderWidth: '3px'
});
PaymentSession.setHoverStyle(["card.number","card.securityCode"], {
borderColor: 'red',
borderWidth: '3px'
});
PaymentSession.setPlaceholderStyle(["card.number", "card.nameOnCard"], {
color: 'blue',
fontWeight: 'bold',
textDecoration: 'underline'
});
PaymentSession.setPlaceholderShownStyle(["card.number", "card.nameOnCard"], {
color: 'green',
fontWeight: 'bold',
textDecoration: 'underline'
});
Using drop-down fields
If you are supporting credit card payments, you can use drop-down values for the hosted fields defining the card expiry month and year.
The following sample code shows how to define the drop-down fields within your payment page’s hosted fields for a credit card payment.
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://eu-gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script>
<!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE -->
<style id="antiClickjack">body{display:none !important;}</style>
</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" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div>
<div>Expiry Month:
<select id="expiry-month" class="form-control input-md" required="" readonly>
<option value="">Select Month</option>
<option value="01">January</option>
<option value="02">February</option>
<option value="03">March</option>
<option value="04">April</option>
<option value="05">May</option>
<option value="06">June</option>
<option value="07">July</option>
<option value="08">August</option>
<option value="09">September</option>
<option value="10">October</option>
<option value="11">November</option>
<option value="12">December</option>
</select>
</div>
<div>Expiry Year:
<select id="expiry-year" class="form-control input-md" required="" readonly>
<option value="">Select Year</option>
<option>21</option>
<option>22</option>
<option>23</option>
<option>24</option>
<option>25</option>
<option>26</option>
<option>27</option>
<option>28</option>
<option>29</option>
<option>30</option>
<option>31</option>
<option>32</option>
<option>33</option>
<option>34</option>
<option>35</option>
<option>36</option>
<option>37</option>
<option>38</option>
<option>39</option>
</select>
</div>
<div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="4" readonly></div>
<div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="3" readonly></div>
<div><button id="payButton" onclick="pay();">Pay Now</button></div>
</script>
</body>
</html>
Configure accessibility
The Hosted Session provides functionality to improve the accessibility of your web site. For more information on web site accessibility, see the WCAG 2 Overview.
Setting the payment page language
To set the language of your overall payment page, add the lang attribute to the <html> element. Defining the page language helps assistive technologies render the text more accurately.
<html lang="en">
<head></head>
<body></body>
</html>
Setting the hosted field locale
To define the locale (language and region) of your hosted fields, add the locale argument to the PaymentSession.configure() function used to configure your session.
When you define the hosted field locale, the Session JavaScript library provides applicable translations for all the textual elements related to the hosted fields, including hidden labels and error messages. If the locale is not set, it defaults to English (en_US).
The supported locale values are de_DE, el_GR, en_US, es_MX, es_ES, fr_CA, fr_FR, it_IT, ja_JA, pl_PL, pt_BR, ro_RO, and zh_CN.
lang attribute) matches the locale of the hosted fields.
PaymentSession.configure({
fields: {
card: {
nameOnCard: cardHolderNameField ? "#card-holder-name" : null,
number: "#card-number",
securityCode: "#security-code",
expiryMonth: "#expiry-month",
expiryYear: "#expiry-year"
}
},
frameEmbeddingMitigation: ["javascript"],
locale:"fr",
callbacks: {
}
});
Improving user experience for hosted fields
The following options allow you to better control the user experience for payers with accessibility needs:
- Setting the iFrame title
The hosted field's iFrame title attribute can be controlled using the title attribute on the field. The title represents advisory information for the field, such as a tooltip.
- Setting ARIA (Accessibility Rich Internet Application) attributes
The Hosted Session supports various aria-* attributes, which you can use to allow assistive technologies help the payer. For example, the aria-label attribute provides a label that assistive technology can read to identify the hosted field for the payer.
- Setting the display parameter for invalid characters
Consider accepting all characters in hosted fields for a better user experience when using assistive technology. To do this, set
interaction.displayControl.invalidFieldCharacters=ALLOWwithin the configuration object argument of thePaymentSession.configure()function. - Setting hidden label and error messages
All hosted fields contain a hidden label and all mandatory hosted fields contain a hidden error message. Any errors resulting from invoking the
PaymentSession.updateSessionFromForm()function raise an error message label. You can additionally raise your own errors using thePaymentSession.setMessage()function.For example, the hidden label for the card number field is Card Number. The hidden error message for missing card number is Card Number is missing, please enter the value. The hidden error message for invalid card number is Card Number is invalid, please enter correct value. While tabbing between the hosted fields, the screen reader reads only the hidden label and hidden error message, not the actual label or error message displayed on the page.
<!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <div>Cardholder Name: <input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="1" readonly></div> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="2" readonly></div> <div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="3" readonly></div> <div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="4" readonly></div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="card security code" value="" tabindex="5" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div>
Handling field focus
The default HTML5 auto-focus behavior does not work with hosted fields: when the payer clicks the label, focus is not automatically moved to the corresponding input element.
To ensure correct focus functionality on your page, use the setFocus() function of the Session JavaScript library.