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 thecustomOptionsobject), 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.

Example:

Copied!
<head>
    <title>Customer Example</title>
    <script src='https://payments.worldpay.com/resources/hpp/integrations/embedded/js/hpp-embedded-integration-library.js'></script>
</head>

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:

Copied!
<!-- 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:

Copied!
<!-- 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.

Code for a webpage in which a basic iframe integration is used:

Copied!
<!DOCTYPE html>
<html>

<head>
    <title> My test page </title>
    <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>
    <div id='custom-html'></div>
    <script type="text/javascript">
        //your options
        var customOptions = {
            iframeHelperURL: 'https://example.com/helper.html',
            url: 'https://payments.worldpay.com/ngpp/integration/wpg/corporate?OrderKey=YOUR_ORDER_KEY&Ticket=YOUR_TICKET_ID',
            type: 'iframe',
            inject: 'onload',
            target: 'custom-html',
            accessibility: true,
            debug: false,
            language: 'en',
            country: 'gb',
            preferredPaymentMethod: 'VISA-SSL',
            successURL: 'https://example.com/success',
            cancelURL: 'https://example.com/cancel',
            failureURL: 'https://example.com/failure',
            pendingURL: 'https://example.com/pending',
            errorURL: 'https://example.com/error'
        };
        //initialise the library and pass options
        var libraryObject = new WPCL.Library();
        libraryObject.setup(customOptions);
    </script>
</body>

</html>

Code for a webpage in which a basic lightbox integration is used:

Copied!
<!DOCTYPE html>
<html>
   <head>
      <title> My test page </title>
      <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>
      <div id='custom-html'></div>
      <a href='#' id='custom-trigger'>Click me</a>
      <script type="text/javascript">
         //your options
         var customOptions = {
         iframeHelperURL: 'https://example.com/helper.html',
         url: 'https://payments.worldpay.com/ngpp/integration/wpg/corporate?OrderKey=YOUR_ORDER_KEY&Ticket=YOUR_TICKET_ID',
         type: 'lightbox',
         trigger: 'custom-trigger',
         lightboxMaskOpacity: 80,
         lightboxMaskColor: '#000000',
         accessibility: true,
         debug: false,
         language: 'en',
         country: 'gb',
         preferredPaymentMethod: 'VISA-SSL',
         successURL: 'https://example.com/success',
         cancelURL: 'https://example.com/cancel',
         failureURL: 'https://example.com/failure',
         pendingURL: 'https://example.com/pending',
         errorURL: 'https://example.com/error'
         };
         //initialise the library and pass options
         var libraryObject = new WPCL.Library();
         libraryObject.setup(customOptions);
      </script>
   </body>
</html>

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:

SettingRequiredDefaultDescriptionType
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: https://payments.worldpay.com/ngpp/integration/wpg/corporate?OrderKey=YOUR_ORDER_KEY&Ticket=YOUR_TICKET_ID
String
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: https://www.example.com/helper.html

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

String
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: https://www.example.com/success.html
String
cancelURLYesn/aThe URL to redirect the shopper to if the payment is cancelled.
For example: https://www.example.com/cancel.html
String
failureURLNon/aThe URL to redirect the shopper to if the payment fails.
For example: https://www.example.com/failure.html
String
pendingURLYesn/aThe URL to redirect the shopper to if a pending payment status is returned.
For example: https://www.example.com/pending.html
String
errorURLYesn/aThe URL to redirect the shopper if there is an unrecoverable error during the payment processing.
For example: https://www.example.com/error.html
String
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.

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

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

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

Iframe only

SettingRequiredDefaultDescriptionType
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.
String
hideContentNofalseHides the iframe.Boolean
SettingRequiredDefaultDescriptionType
triggerYesn/aThe ID for the element that will trigger the lightbox.

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

String
lightboxMaskOpacityNo50The custom opacity (%) of the lightbox.
Possible values:
0-100
No
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.
Boolean

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.

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

Destroy

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

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

Callbacks

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.

Example:

Copied!
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. This can be used as an alternative to result URLs (successURL, failureURL etc.), by specifying a resultCallback option, as seen in thecustomOptions table. 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:

Copied!
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 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.

Copied!
{
   "order":{
     "orderKey":"MERCHANT1^1234567890",
     "status":"success"
   },
   "error":null,
   "gateway":{
     "paymentAmount":"123",
     "paymentCurrency":"EUR",
     "mac":"b75c0d26766582f952588645a1c7e731",
     "paymentStatus":"AUTHORISED",
     "orderKey":"ADMIN^MERCHANT1^1234567890"
   }
 }