My test page

**Last updated**: 14 June 2025 | [**Change log**](/products/hosted-payment-pages/changelog/) # Iframe SMB (Worldpay eCommerce) 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 `` tags of your website: ``` ``` ### Step 2: Create the target container Create a container on your website, where the iframe is injected: ```

``` 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 My test page

This is my test page as a merchant

### 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](#callbacks) for information. | | `flowCallback` | ❌ | JavaScript Function | n/a | Sends back what page is being shown. See [Callbacks](#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](https://developerengine.fisglobal.com/apis/wpg/reference/customisationoptions). | #### 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. | #### Lightbox-only parameters | Parameter | M/O/C | Type | Default | Description | | --- | --- | --- | --- | --- | | `trigger` | ✅ | String | n/a | The ID for the element that triggers the lightbox. 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. 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. 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](/products/hosted-payment-pages/webhooks) to receive the latest status of your payment to your server in real-time. ## Managing your payments Log into your [Dashboard](https://dashboard.worldpay-bsh.securedataplatform.com) to manage your payments. You can: * view * refund your payments. br **Next steps** [Customization](/products/hosted-payment-pages/customization) [Add Webhooks](/products/hosted-payment-pages/webhooks) [Testing](/products/hosted-payment-pages/testing)