Customise the look and feel

Hosted Session allows you to style hosted fields to match the look and feel of the replaced fields on your payment page.

You can invoke the following functions for styling.

  • setFocus( ): Sets focus on the specified hosted field.
  • setFocusStyle( ): Sets the styling attributes for the specified hosted fields when the focus is gained.
  • setHoverStyle( ): Sets the styling attributes for the specified hosted fields when a mouse hover occurs.
PaymentSession.setFocusStyle(["card.number","card.securityCode"], {
  borderColor: 'red',
  borderWidth: '3px'

PaymentSession.setHoverStyle(["card.number","card.securityCode"], {
  borderColor: 'red',
  borderWidth: '3px'

Listen to events on Hosted Fields

Hosted Session allows you to register callback functions to handle events that may occur on the Hosted Fields during the payer’s interaction.

You can register callback functions for the following events:

  • onChange( ): Invoked when the input value in the hosted field in the iFrame has changed.
  • onFocus( ): Invoked when the hosted field in the iFrame has gained focus.
  • onBlur( ): Invoked when the hosted field in the iFrame has lost focus.
  • onMouseOver( ): Invoked when a mouse over event occurs in the hosted field.
  • onMouseOut( ): Invoked when a mouse out event occurs in the hosted field.

Detailed information about each callback is found in Callbacks in the left-hand side panel of this guide.

See the code block below (lines 6-20) for a clear example of how callbacks are used.

Drop-down fields for expiry month and year

Hosted Session allows you to use drop-down values for the expiry month and expiry year. See the sample code below (lines 8-39).

Create the HTML
Optional Month/Year Fields


<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>
<div>Expiry Year: 
<select id="expiry-year" class="form-control input-md" required="" readonly>
	<option value="">Select Year</option>

Hosted Session: Useful parameters, functions and callbacks

The Scope parameter

This section will describe how to use the scope parameter (in particular, how to use it to validate fields).

  • PaymentSession.configure(‘configuration’, scope)

The scope parameter on the following Hosted Session calls becomes mandatory once the initial PaymentSession.configure( ) call is invoked with scope.

  • PaymentSession.updateSessionFromForm(‘card’, ‘card-type’, scope)
  • PaymentSession.setFocus(‘cardNumber’, scope)

The scope parameter is optional on the following calls if an interaction is configured with a scope. If a scope is not specified on the calls, the function/callback will apply to all card data sets within the hosted iFrame.

  • PaymentSession.setFocusStyle([], styles, scope)
  • PaymentSession.setHoverStyle([], styles, scope)
  • PaymentSession.onFocus([],function(selector), scope)
  • PaymentSession.onBlur([], function(selector), scope)
  • PaymentSession.onChange([], function(selector), scope)
  • PaymentSession.onMouseOver([], function(selector), scope)
  • PaymentSession.onMouseOut([], function(selector), scope)
Create the HTML
Listen to events
 * Provide an array of field roles for proxy fields as the first parameter
 * Each callback function is invoked with the selector for the field whose proxy triggered the event.
PaymentSession.onBlur(['card.number'], function(selector) {
    //handle blur event
PaymentSession.onFocus(['card.number', 'card.securityCode'], function(selector) {
    //handle focus event
PaymentSession.onChange(['card.securityCode'], function(selector) {
    //handle change event
PaymentSession.onMouseOver(['card.number'], function(selector) {
    //handle mouse over event
PaymentSession.onMouseOut(['card.number'], function(selector) {
    //handle mouse out event