Last Updated: 25 June 2024 | Change Log

Iframe

Worldpay eCommerce 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="https://payments.worldpay.com/resources/hpp/integrations/embedded/js/hpp-embedded-integration-library.js"></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>

Warning

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>
<html>
    <head>
        <title>My test page</title>

        <!-- Add the Hosted Payment Pages JavaScript library to your page -->
        <script src="https://payments.worldpay.com/resources/hpp/integrations/embedded/js/hpp-embedded-integration-library.js"></script>
    </head>

    <body>
        <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: 'https://payments.worldpay.com/app/hpp/integration/transaction/37d9d008-d649-4458-a7cd-c07a65debc54?ref=1718718877578485&cs=JWNvp6kQ0Xsrca_q',
                type: 'iframe',
                inject: 'onload',
                target: 'custom-html',
                accessibility: true,
                debug: false,
            };
            // Initialize the library and pass options
            var libraryObject = new WPCL.Library();
            libraryObject.setup(customOptions);
        </script>
    </body>
</html>

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:

Parameter	M/O/C	Type	Default	Description
`url`	✅	String	n/a	The Hosted Payment Pages session URL, sent in the response of your initial request. The URL is for the Hosted Payment Pages.
`target`	✅	String	n/a	The ID for the element into which the iframe is injected.
`type`	❌	String	lightbox	Indicates whether you are using an iframe or lightbox integration. Possible values: `iframe` or `lightbox`.
`debug`	❌	Boolean	false	When set to true, debug messages are written to the console.
`resultCallback`	❌	JavaScript Function	n/a	The function to call when the payment process is complete. See Callbacks for information.
`flowCallback`	❌	JavaScript Function	n/a	Sends back what page is being shown. See Callbacks for information.
`disableScrolling`	❌	Boolean	false	If set to "true", will stop the checkout page from scrolling.
`customisation`	❌	String	n/a	Describes the styling of the page. Possible options can be found here.

Iframe-only parameters

Parameter	M/O/C	Type	Default	Description
`inject`	❌	Boolean	`default`	Controls 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"
`hideContent`	❌	Boolean	`false`	Hides the iframe.

Parameter	M/O/C	Type	Default	Description
`trigger`	✅	String	n/a	The ID for the element that triggers the lightbox. Info You must provide an ID for the trigger setting.
`lightboxMaskOpacity`	❌	String	50	The custom opacity (%) of the lightbox. Possible values: 0-100
`lightboxMaskColor`	❌	String	#000000	The custom color (hex value) for the close button.
`accessibility`	❌	Boolean	false	Controls 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. Info 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

Destroy

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

var libraryObject = new WPCL.Library();  
...
libraryObject.destroy();

Callbacks

Flow callback

Allows you to pass your own JavaScript function to our library, which is invoked when a page loads.

Info

Currently only supports card details page.

var flowCallbackFunction = function(result) {
    alert(result.page);
};

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":
       redirectUrl="https://example.com/success";
       break;
     case "failure":
       redirectUrl="http://example.com/failure";
       break;
     case "error":
       redirectUrl="https://example.com/error";
       break;
     default:
       redirectUrl="http://example.com/unknown";
   }
   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

{
   "order":{
     "orderKey":"MERCHANT1^1234567890",
     "status":"success"
   },
   "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

Customization
Add Webhooks
Testing