Last Updated: 09 May 2024 | Change Log


Worldpay for Business merchants only

Use our JavaScript library to embed Hosted Payment Pages inside an iframe (inline frame) on your pages.

This is particularly useful if you want to display content around the payment pages, keep the customer on your website or blend our payment pages into your existing website.

Basic integration

Step 1: Embed our JavaScript library

Add the following snippet to the <head></head> tags of your website:

<script src=""></script>

Step 2: Create the target container

Create a container on your website, where the iframe is injected:

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

Do not present Hosted Payment Pages within an additional iframe which isn’t generated by our library. Doing so, results in an error message (X-Frame = DENY) and non-uniform integration.

Step 3: Invoke our JavaScript library

Create a new instance of our JavaScript library and invoke the setup function, passing options to setup and customize your iframe integration.

Full example

<!DOCTYPE html>
        <title>My test page</title>

        <!-- Add the Hosted Payment Pages JavaScript library to your page -->
        <script src=""></script>

        <div>This is my test page as a merchant</div>

        <!-- Add a container for where the Hosted Payment Pages iframe is injected -->
        <div id="custom-html"></div>

        <!-- Use JavaScript to inject the iframe into the container -->
        <script type="text/javascript">
            // Your custom options for injecting the iframe
            var customOptions = {
                url: '',
                type: 'iframe',
                inject: 'onload',
                target: 'custom-html',
                accessibility: true,
                debug: false,
            // Initialize the library and pass options
            var libraryObject = new WPCL.Library();

JavaScript parameters

Below is a full list of parameters you can pass into the setup function, some are mandatory. Others are used to customize the flow and presentation of your iframe / lightbox integration:

urlStringn/aThe Hosted Payment Pages session URL, sent in the response of your initial request. The URL is for the Hosted Payment Pages.
targetStringn/aThe ID for the element into which the iframe is injected.
typeStringlightboxIndicates whether you are using an iframe or lightbox integration. Possible values: iframe or lightbox.
debugBooleanfalseWhen set to true, debug messages are written to the console.
resultCallbackJavaScript Functionn/aThe function to call when the payment process is complete. See Callbacks for information.
flowCallbackJavaScript Functionn/aSends back what page is being shown. See Callbacks for information.
disableScrollingBooleanfalseIf set to "true", will stop the checkout page from scrolling.
customisationStringn/aDescribes the styling of the page. Possible options can be found here.

Iframe-only parameters

injectBooleandefaultControls how the iframe is injected. Possible options:
  • onload - occurs on page load
  • immediate - immediately inject the iframe
  • default

We recommend to use onload as default will be removed in the future.

Depending on the web development framework you use, you may need to choose "immediate" instead of "onload"
hideContentBooleanfalseHides the iframe.
triggerStringn/aThe ID for the element that triggers the lightbox.
You must provide an ID for the trigger setting.
lightboxMaskOpacityString50The custom opacity (%) of the lightbox.
Possible values:
lightboxMaskColorString#000000The custom color (hex value) for the close button.
accessibilityBooleanfalseControls 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.
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


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

var libraryObject = new WPCL.Library();  


Flow callback

Allows you to pass your 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.

You can use this as an alternative to result URLs (successURL, failureURL etc.), by specifying a resultCallback option. Therefore, leave such result URL options unspecified as they have higher precedence.

The following function uses the order status to redirect to different pages, appending gateway parameters to the end of the URL:

function(responseData) {
   var redirectUrl;
   var status = responseData.order.status;
   switch (status) {
     case "success":
     case "failure":
     case "error":
   window.location = redirectUrl;

Data structure

Your callback function should take a single parameter, which is 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 customer's session
      • cancelled_by_shopper - the customer has cancelled the order
      • session_expired - the customer's session has expired
    • error
      • referenceNumber - if an exception occurred this includes a unique reference number, otherwise this is not defined
    • gateway - parameters sent by the payment gateway, currently unused
   "error": null,
   "gateway": null

Payment status

To manage your payments we recommend using our webhooks to receive the latest status of your payment to your server in real-time.

Managing your payments

Log into your Dashboard to manage your payments. You can:

  • view
  • refund

your payments.

Next steps

Add Webhooks