This page describes the third party Javascript libraries and provided Javascript features, that are available in hosted when using a version 2 skin, see Skin properties for details.
Contents:
Provided Libraries
jQuery
By default the jQuery library is included on hosted pages, so that its Javascript features are available for use by skin Javascript. For maximum browser support we use the latest 1.x version, at time of writing we use 1.12.3, this may be upgraded to more recent 1.x releases without notice.
A skin can stop jQuery from being included on the page by using the skin property:
includeJquery=false
However, all provided javascript skin features documented here require jQuery. So if a skin excludes jQuery none of these other features will be available.
Bootstrap
By default the Boostrap CSS and Javascript libraries are included on hosted pages. Much of the hosted HTML includes bootstrap classes, so a base level of styling comes automatically.
Boostrap can be excluded by using the skin property:
includeBootstrap=false
Respond & HTML5 Shiv
To enhance the behaviour of hosted in older browsers, specifically old versions of Internet Explorer, the Respond and HTML5 Shiv libraries are included on all hosted pages. See documentation for each tool for full details of the functionality provided.
Each can be excluded from hosted HTML by using skin properties:
includeRespond=false includeHtml5Shiv=false
Provided Features
Payment Method Logic
When there are multiple available payment methods, they are rendered into the HTML as a radio control. For each payment method there can be multiple fields, specially for cards. In practice the customer only needs to see the fields for the currently selected payment method. This script hides the details of the unselected payment methods.
Additionally it binds the ‘required’ attribute to only the appropriate visible form fields.
This script can be disabled with a skin property:
includePaymentMethodLogic=false
Validation
The validation logic is linked to ‘blur’ events on all the form fields. If the value entered into any is invalid then a message will be shown. For example:
<div class="form-group pan-group has-error">
<label for="cardRegistration.pan" class="control-label pan-label">
<span>Card Number</span>
</label>
<div class="control-wrapper number-control-wrapper pan-control-wrapper">
<input type="tel" autocomplete="off" id="cardRegistration.pan" class="form-field pan-value" name="cardRegistration.pan.value" value="" required="required">
<span class="help-block error-message pan-error-message">You must enter a valid card number</span>
</div>
</div>See Skin CSS for more details on validation message.
The Javascript based client side validation can be disabled by a skin property:
includeClientValidation=false
The skin can also alter the client side validation logic, see Customising client-side validation.
Field Entry
This script provides two features:
First, many of the fields in a payment form are numeric only, PAN, amount, security code to name a few. This feature intercepts all entry into these fields and stops non-numeric characters from being typed in. This helps prevent the user from accidentally typing in invalid content.
Second, for the PAN field, as the card number is entered, spacing will be added to format the number as the user sees it on their card. By default it will use the most common pattern of 4 groups of 4 digits, as used by Mastercard and Visa. If the Card Brand Lookup feature is also in use then the spacing will change based on the type of card being entered, to be the layout for that particular brand.
This can be disabled with a skin property:
formEntry=false
The skin can also alter the form entry logic, see Customising form entry behaviour.
Card Brand Lookup
As the user enters their card number, this script will look at the first few digits and from that determine what brand of card it is. It will show the appropriate card brand logo next to the card number input field on the page. If the Field Entry feature is also in use, then the card spacing will change to be appropriate for the brand.
This feature can be disabled with a skin property:
cardBrandLookup=false
This lookup is based on the first few digits of the card only. Card issuing institutions trade card IIN (Institution Issuing Number) ranges, using only the first few digits is generally okay but not completely reliable. For more accurate information the Card Info service can be used.
Card Info
The Card Info Library is not automatically available and needs to be purchased as an add on for your account. If activated then the card brand will be detected based on a full detailed listing of current IINs in use.
Should you wish for hosted not to use the Card Info Library, it can be disabled with a skin property. When disabled the regular fixed-digit brand lookup will be used.
cardInfo=false
Here are some examples of using the Card Info Library: Custom card behaviour
Custom Javascript
Any additional Javascript in the skin needs to be included in a single file, in the zip as /assets/js/main.js. This can contain any code, however Pay360 will need to perform due diligence checks on it before it can be put into our production environment.
Session Data
In the skin Javascript it can be useful to know information about the current hosted session, to drive dynamic behaviour. To this effect an object Hosted is initialised by the pages, it contains information detailing the current session.
|
Variable
|
Description
|
Example
|
|---|---|---|
| Hosted.Cashier.basePath | The base path of the web application | ‘/hosted’ |
| Hosted.Cashier.resourcePath | The base URL for all skin assets | ‘/hosted/SMjpHvxh_5cNPAZpgJ8MKuUk_/skin/1234’ |
| Hosted.Cashier.flow | The type of hosted session, can be:
|
‘PAYMENT’ |
| Hosted.Cashier.sessionAmount | Information about the amount of the payment. | Fixed Amount
Range Amount Amount Options |
| Hosted.Cashier.cardList | Only defined on the card list selection page, and the card management page.
It contains details about the available cards. |
|
| Hosted.Cashier.locale | The locale in use, and all the message keys available (including those from the skin) for the given locale.
Useful to dynamically show messages for the correct locale, see Skin localisation for more information |
|
Skin Fields
It is possible to use the hosted initialisation API request to provide data for the skin Javascript to use. The data must be in a JSON structure and cannot contain any Javascript code, it can only be used to inject numbers and text.
Example Hosted Initialisation Request
{
"session" : {
"returnUrl" : {
"url" : "http://www.example.com/merchant/transactionResult?MERCHANTREF=txn-1234"
}
},
"transaction" : {
"merchantReference" : "txn-1234",
"money" : {
"currency" : "GBP",
"amount" : {
"fixed" : 39.95
}
},
"description" : "Hats, shoes and a coat"
},
"customFields" : {
"dataFieldOrTextFieldOrLabelField" : [
{
"skinField" : {
"format" : "application/json",
"name" : "cart",
"value" : "{ 'items' : [
{ 'name' : 'Hat', 'quantity' : '4', 'price' : '4.99' },
{ 'name' : 'Shoes', 'quantity' : '1', 'price' : '1.99' },
{ 'name' : 'Coat', 'quantity' : '2', 'price' : '9.00' }
] }"
}
}
]
}
}
NB! Note that the content of the skin field ‘value’ attribute is text that contains JSON, and not an element within the JSON request itself.
This will be made available to the skin in a global array called ‘skinFields’ keyed by the field name.
<script type="text/javascript">
var skinFields = [];
skinFields['cart'] = {
"items" : [
{ "name" : "Hat", "quantity" : "4", "price" : "4.99" },
{ "name" : "Shoes", "quantity" : "1", "price" : "1.99" },
{ "name" : "Coat", "quantity" : "2", "price" : "9.00" }
]
};
</script>
This can then be used to render custom content onto the page, such as a shopping cart.
Multiple Javascript Files
It may be inconvenient to include all the skin Javascript in the one main.js file, or you may wish to use a third party library such as a jQuery plugin. Only main.js will be imported by the HMTL, however the jQuery getScript() function can be used to import others using a relative path. Say for example next to main.js you have form.js, and a jquery plugin in the skin in /assets/plugins/jquery.plugin.js, then in main.js include
$.getScript("form.js");
$.getScript(Hosted.Cashier.resourcePath + "/assets/plugins/jquery.plugin.js");
By default getScript loads asynchronously, which may cause problems if you wish to use the features of the plugin immediately. The load can be made synchronous.
$.getScript({
url: Hosted.Cashier.resourcePath + "/assets/plugins/jquery.plugin.js",
async: false
});
Additional Third Party Libraries
If you wish to use any third party libraries other than the ones already provided in the skin, then they need to be embedded within the main.js file or loaded as shown above. Please ensure the source and version are commented in the library source, so during due diligence checks it can be confirmed this is the unmodified code as downloaded from the third party supplier. This is essential as usually such code is minified and rendered unreadable. The skin will not be approved for production use without the library being verified.
Content Security Policy
All hosted pages are served with a Content Security Policy (CSP) which tells the web browser to only load other content from Pay360 domains. This provides protection for the user as no content can be injected from other domains. For the skin Javascript that means it cannot reference images or resources from other domains. Any such resources have to be put inside the skin zip and referenced from the Javascript with relative paths, or built from the Hosted.Cashier.resourcePath variable.