Hosted Payment Page Library
A simple client-side script is available to simplify the displaying of the Hosted Payment Page in a lightbox overlaying your website.
The library is available as a JavaScript script and is based around a single class: the Form class. The script is compatible with most modern web browsers.
The script can be loaded directly from our Gateway server as follows[1].
<script src="https://gateway.example.com/sdk/web/v1/js/hostedforms.min.js"></script>
If the script detects the presence of the jQuery API, then it will extend the jQuery object with its own plugin method. However, jQuery is not needed in order to use the script.
[1] Please use the correct hostname as explained in the Prerequisites section.
Hosted Payment Pages
Hosted Payment Pages are a prebuilt webpage residing on our server that you can use to collect sensitive payment details without those details’ touching your server. The standard Hosted Payment Page is designed so that it can be displayed in a transparent overlay over your website, thus making the Customer feel as though they never left your shopping cart.
The standard Hosted Integration examples redirect the Customer’s browser to the Hosted Payment Page, resulting it appearing on a new browser page and not overlaying your website. The Hosted Payment Page library provides the scripting necessary to result in the redirection, causing the Hosted Payment Page to appear in an overlay and not a new browser page, without your having to make any modifications to your website. The library can also simplify the creation of the Hosted Integration redirection FORM if required
Library Namespace
To avoid polluting the global namespace, the library extends the global window object with a hostedForms object containing the following properties:
· forms – array containing all the instantiated Form objects.
· classes – array containing all the instantiable classes.
- form – Form class prototype.
Form Construction
The construction method can be used to build and prepare a HTML FORM element for use with the modal Hosted Payment Page; or to prepare an existing element. The method signature is as follows
Form(element, data)
The element parameter should be either the id or DOM node of an existing FORM or DIV DOM element.
If the element is a DIV node, then the data is used to create a new FORM node within the element.
If the element is a FORM node, then the data is used to modify the existing FORM element.
The data parameter should be an object containing construction details and can contain the following optional properties:
· id – string containing the value to use as the FORM tag’s id attribute.
· url – string containing the URL to use as the FORM tag’s src attribute.
· attrs – object whose properties are added as additional attributes on the FORM tag.
· modal – boolean indicating that the HPP should open in a modal overlay.
· data – object whose properties are added as hidden input elements in the FORM.
· submit – object containing details for a submit button that should be added to the FORM.
- type – type of submit button, either ‘auto’, ‘image’, ‘button’, ‘input’
- id – string containing the value to use as the submit button’s id attribute.
- attrs – object whose properties are added as additional attributes on the submit button.
- label – string containing button label (or ‘alt’ attribute for ‘image’ buttons)
- src – string containing image URL for ‘image’ buttons.
The constructor will submit the FORM immediately after preparation if the data.submit.type property is ‘auto’; or if the existing FORM element has a data-hostedform-autosubmit attribute. Otherwise, an event handler will be attached to the submit button to disable it automatically when clicked, to help prevent your Customer from clicking it twice.
The constructor will prepare the FORM so that the Hosted Payment Page (HPP) will be opened in a modal overlay if the data.modal property is true; or if the existing FORM element has a data-hostedform-modal attribute; or has an action attribute containing the string ‘modal/’ or ending in the string ‘modal’.
The modal overlay is automatically created as a semi-opaque IFRAME element that fills the browser display. The Hosted Payment Page is then loaded into this IFRAME and being semi-opaque, your shopping cart will remain visible beneath, but greyed out and noninteractive. When the Customer closes the Hosted Payment Page, then their browser will be redirected to the URL you provided using the redirectURL parameter. This will cause the original page and IFRAME to be replaced by your new page.
Form Methods
The follow methods are made available by the Form class:
void destroy()
Destroys the Form, reverting its element back to its original state.
jQuery Plugin
If the jQuery API has been loaded into the browser before the script, then it will extend the jQuery object with its own plugin method.
Construction and destruction can then be done as follows:
$(element).hostedForm(data);
$(element).hostedForm(‘destroy’);