JavaScript SDK

Use our library to securely embed payment pages on your own site, within an iframe or lightbox. Unfortunately this only supports cards, and does not yet supportAlternative Payment Methods(APMs).

In the iframe setup all Hosted Payment Page content, including 3-D Secure content, is displayed in an iframe within your website.

In the lightbox setup we use an iframe to display 3-D Secure within the lightbox. All other Hosted Payment Page content is displayed in the lightbox.

On this page

Note: In addition to this guidance, we provide a wizard to guide you through the integration process for iframe or lightbox. Using the wizard, you can download the helper file, specify parameters and generate code snippets. The wizard is available athere.

Required files

These files are required for an iframe or lightbox integration:

File namePurposeAction required
helper.htmlThe helper file is used by hpp-embedded-integration-library.js (see below) to communicate with the parent page on your site. It performs resizing and redirection actions.You must host this file in the same domain as the webpage into which you are integrating the iframe or lightbox. Hosting the helper file in this way ensures that the iframe or lightbox dynamically resizes in response to the content being shown.

Note: You can rename the helper file (reference the new name in the iframeHelperURL parameter in the customOptions object), but do not make any other changes to it.

hpp-embedded-integration-library.jsCreates an iframe or lightbox in your web page and connects it to the Hosted Payment Pages.We host this file on the Worldpay domain.

Note: Do not host or cache this file on your website.

Download the helper file

Download and host the helper.html file to your website. This file communicates with your website to resize the iframe or lightbox with the content being shown. It must be hosted in the same domain as the webpage in which you are integrating the iframe or lightbox.

You can download a copy of the helper file from the Worldpay embedded integration wizardhere.

Update your website

Update the code on the webpage in which the iframe or lightbox is displayed. For example, your web page might contain a Check out button or link. When the shopper clicks to check out, the code triggers the display of the iframe or lightbox.

To update the code on your website, complete the following steps:

  1. Add our Javascript library to your page
  2. Create your markup
  3. Invoke our Javascript library

1. Add our Javascript library to your page

In the code for the webpage that will display the iframe or lightbox, insert references to:

  • hpp-embedded-integration-library.js

Warning: We make periodic updates to these files. To ensure that you have the latest versions, do not host or cache these files on your website.


    <title>Customer Example</title>
    <script src=''></script>

2. Create your markup

Note: Do not present the Worldpay Hosted Payment Pages within an additional iframe or lightbox which isn’t generated from the Worldpay SDK. Doing so will result in an error message (X-Frame = DENY) and non-uniform integration. There's more about this introubleshoot.

Use a <div> to create a region on the page for the placement of the iframe/lightbox:

<!-- html container element -->  
<div id='custom-html'></div>

You can use an element (such as a button) to trigger the display of the lightbox. When a shopper clicks the button, the lightbox containing the Hosted Payment Pages is displayed:

<!-- html button element -->  
<a href="#" id="id_trigger" class="button">Click me </a>

3. Invoke our Javascript library

Create a new instance of our JavaScript library and invoke the setup function, passing options to setup and customise your iframe / lightbox integration. A full list of available options can be found in the next sectionSetup Options.

Setup Options

Below is a full list of options that can be passed into the setup function, some are mandatory. Others are used to customise the flow and presentation of your iframe / lightbox integration:

typeNolightboxIndicates whether you are using an iframe or lightbox integration. Possible values: iframe or lightbox.String
urlYesn/aThe redirect URL that we send you in response to a valid XML order. The URL is for the Hosted Payment Pages.
For example:
targetYesn/aThe ID for the element into which the iframe will be injected.String
iframeHelperURLYesn/aThe URL of the helper library that you are hosting on your website
For example:

Note: This property is mandatory for both iframe and a lightbox integration.

debugNofalseWhen set to true, debug messages are written to the console.Boolean
languageNoenThe default language setting for the payment pages.String
countryNogbThe default country setting for the payment pages.String
preferredPaymentMethodNon/aThe preferred payment method. Ensure that the preferred payment method is available in the country specifiedString
successURLYesn/aThe URL to redirect the shopper to when the payment is successfully completed.
For example:
cancelURLYesn/aThe URL to redirect the shopper to if the payment is cancelled.
For example:
failureURLNon/aThe URL to redirect the shopper to if the payment fails.
For example:
pendingURLYesn/aThe URL to redirect the shopper to if a pending payment status is returned.
For example:
errorURLYesn/aThe URL to redirect the shopper if there is an unrecoverable error during the payment processing.
For example:
resultCallbackNon/aThe function to call when the payment process is complete. SeeCallbacksfor information.Javascript function
flowCallbackNon/aSends back what page is being shown. SeeCallbacksfor information.Javascript function
disableScrollingNofalseIf set to "true", will stop the checkout page from scrolling.Boolean
iframeIntegrationIdNon/aSpecifies the name of the reference to the integration library.
For example: libraryObject

Note: This is no longer required and can be removed.

iframeBaseURLNon/aThe URL of the webpage on your website that is hosting the integrated payment pages.
For example:

Note: This is no longer required and can be removed.

customisationNon/aDescribes the styling of the page. Possible options can be foundhere.Javascript option

Iframe only

injectNodefaultControls how the iframe is injected. Possible options:
  • onload - occurs on page load
  • immediate - immediately inject the iframe
  • default - similar to onload but deprecated, will wipe out your window load events.

Worldpay recommends to use onload as default will be removed in the future.
hideContentNofalseHides the iframe.Boolean
triggerYesn/aThe ID for the element that will trigger the lightbox.

Note: You must provide an ID for the trigger setting.

lightboxMaskOpacityNo50The custom opacity (%) of the lightbox.
Possible values:
lightboxMaskColorString#000000The custom colour (hex value) for the close button.Integer
accessibilityNofalseControls user access to content outside of the lightbox.
When set to true, the user can access content in the lightbox only. Access to the parent webpage is prevented.

Note: To prevent customers from inadvertently leaving the payment pages, we recommend that you set accessibility to true.

When set to false, the user can access content in the lightbox and also in the parent webpage.

Library Functions

Populate payment details (example for cards page):

Allows you to populate the form fields on the page, from outside the iframe. Use the flow callbacks to ensure the page has finished loading.

var libraryObject = new WPCL.Library();  
  cardNumber: "4444333322221111",
  cardHolderName: "AUTHORISED",
  cardExpiryMonth: 12,
  cardExpiryYear: 49,
  cardSecurityCode: "123"


Use the below destroy function to clean up your lightbox/iframe.

var libraryObject = new WPCL.Library();  


Flow Callback

Allows merchants to pass their own JavaScript function to our library, which is invoked when a page loads. Currently only supports card details page.


var flowCallbackFunction = function(result) {

var customOptions = {
  flowCallback: flowCallbackFunction

Result Callback

A result callback allows your own JavaScript function to be invoked at the end of the payment flow, or when a payment attempt is made. This can be used as an alternative to result URLs (successURL, failureURL etc.), by specifying a resultCallback option, as seen in the customOptions table. Therefore, leave such result URL options unspecified as they have higher precedence.

Data Structure

Your callback function should take a single parameter, which will be passed as a JSON object. This contains details about an attempted order/payment.

It has the following structure:

  • order

    • orderKey - the order key used to process the payment
    • status - the status of the payment. It is one of the following:
      • success - the payment is successful
      • pending - the payment is pending
      • failure - the payment has failed
      • error - a gateway error has occurred
      • exception - a problem has occurred during the shopper's session
      • cancelled_by_shopper - the shopper has cancelled the order
      • session_expired - the shopper's session has expired
    • error
      • referenceNumber - if an exception occurred this will include a unique reference number, otherwise this will not be defined
    • gateway - parameters sent by the payment gateway, such as the MAC and paymentCurrency

    Gateway parameters vary according to the payment method used, and other settings. These parameters are only provided if you have enabled the Send URL parameter in the Payment Page Designer, and the shopper has attempted a payment. See theXML HPP Integration guidefor more information.