Menu

Payment page integration

For each installationId you have, you can specify a different integration type, a different set of parameters and a differentHosted Payment Page design. For example, each installationId could represent a distinctive customisation for different territories, or national holidays.

Integration type

Your integration type decides how you set your parameters.

Full-page redirect

Full-page is right for you if you takeAlternative Payment Methods(APMs) through Worldpay, as well as card payments. Currently the iframe/lightbox integration doesn't support APMs.

In the full-page integration we use an iframe to display 3D Secure. All other Hosted Payment Page content is displayed full page in the browser.

JavaScript SDK

JavaScript SDKis right for you if you want a more advanced integration with card payments only:

  • In the iframe setup all Hosted Payment Page content, including 3D Secure content, is displayed in an iframe within your website.
  • In the lightbox setup we use an iframe to display 3D Secure within the lightbox. All other Hosted Payment Page content is displayed in the lightbox.

Parameters you can send

For each order you send to us, you can specify:

Worldpay parameters

The method for sending Worldpay parameters depends on your integration type, but the parameters themselves are the same:

  • In the full-page integration you append the Worldpay parameters to the redirect URL we send you. All appended parameters and their values must be URL-encoded to ensure correct processing.
  • In the iframe or lightbox integration you instead use acustomOptionsobject to define the below parameters.

For each order you submit to us, we recommend that you specify one or more of these Worldpay parameters:

Shopper's payment method

Providing your shopper's payment method means that they don't need to specify it later in the payment process. Instead, your shopper is immediately redirected to the payment page where they can enter credit card or other payment data. This is useful if:

  • You only want to accept one specific payment method (for this particular transaction)
  • You want to bypass the payment methods presented by Worldpay, because the shopper has already chosen a preferred payment method in the shopping application on your server

The optional preferredPaymentMethod parameter sets the shopper's preferred payment method.

Note: This parameter does not work with Apple Pay, Google Pay and the Pay by Bank App.

Language and country code for the shopper

The optional country and language parameters set the default country and the language of the payment method selection pages:

  • The language parameter applies to the text originating from Worldpay, not to the order description and order content you supplied. For a list of supported languages, seeSupported Languages.
  • The country parameter influences which of the available payment methods are presented to the shopper. For example, if you set thecountry codeas "NL" the shopper would be presented with a range of international credit cards and Netherlands-specific payment methods. If you don't specify a country code or a preferred payment method, all payment methods worldwide for which you are eligible are displayed.

Note: You can also specify the country and the language independently from each other. For example, you could present the payment methods for the Netherlands in Swedish.

Custom result URLs

Provide custom result URLs so that your shoppers are returned to your website at the end of the payment process.

If result URLs are not provided, shoppers are redirected to one of Worldpay's default result pages, where the payment journey ends.

Note: In the iframe integration, you must provide custom result URLs.

You can provide these result URLs:

Payment STATUS/outcomeParameterDescription / Comments
AUTHORISEDsuccessURLThe URL to redirect the shopper to when the payment is successfully completed. For example: https://www.example.com/success.html.
Full-page: append "&successURL=http%3A%2F%2Fwww.example.com%2Fsuccess.asp"
SHOPPER_REDIRECTED <br> or <br> SENT_FOR_AUTHORISATIONpendingURLThe URL to redirect the shopper to if the AUTHORISED result isn't immediately known (which happens with someAlternative Payment Methods). For example:www.example.com/pending.html<br> Full-page: append"&pendingURL=http%3A%2F%2Fwww.example.com%2Fpending.php"
REFUSEDfailureURLThe URL to redirect the shopper to if the payment is refused. For example:www.example.com/failure.html<br> Full-page: append"&failureURL=http%3A%2F%2Fwww.example.com%2Ffailure.php"
Cancelled by the shoppercancelURLThe URL to redirect the shopper to if they cancel the payment. For example:https://www.example.com/cancel.html`
Full-page: append "&cancelURL=http%3A%2F%2Fwww.example.com%2Fcancel.php"
ExpiredexpiryURLThe URL to redirect the shopper when the HPP session expires. For examplehttps://www.example.com/expiry.html
HPP Session ErrorerrorURLThe URL to redirect the shopper when there is an unrecoverable HPP session error. Note: This error is not related to the payment. For example: https//www.example.com/error.html
Full-page: append "&errorURL=http%3A%2F%2Fwww.example.com%2Ferror.php"

Merchant-defined parameters

You can send us custom parameters that are specific to your business. For example, if you use a third party shopping cart, you can specify a reference, such as cart ID.

Before you can use custom parameters, you must specify them in the Extra URL parameters field in thePayment Page Designer.

Warning: If you submit an order with a custom parameter that we are not aware of, your shopper will receive an error and will not be able to complete the order.

To send your custom parameters, append them to the redirect URL that we send you.

We do not use your custom append parameters in the payment process. They are not returned in the result URL. .

Parameters you can receive

You can request to have a basic set of parameters appended to the result URL. These parameters are provided for your information only.

To have these parameters appended, in thePayment Page Designer, go to Edit Payment Pages > Properties > Edit merchant configuration and then set the Send URL parameters field to True.

When this feature is enabled, these parameters are appended to the result URL:

  • Order key

    Note: If the MAC is not set, you will only receive the Order Key.


  • Payment status
  • Payment amount
  • Payment currency
  • Message authentication code (MAC)

Best practice: Do not use these parameters as part of your internal reconciliation process. You should usenotificationsinstead. Notifications are a reliable way of updating the status of payments in your back-office system.

Customising your payment pages

You can customise through the payment page designer. More information on how to do this can be foundhere.

Alternatively you can send individual custom options with each transaction using theJavascript SDK.

In-app integration guidelines

Mobile app integration is not yet officially supported. We will only provide support for the payment pages themselves.

If you choose to integrate with a mobile app, we recommend:

  • Using the most up-to-date Safari or Chrome as the WebView client
  • Not injecting JavaScript, or manipulating the content of the payment pages

Mobile App Integration

Flow Diagram

Instead of using a WebView, Worldpay strongly recommend opening the HPP order URL (returned from your payment request) in the mobile’s default browser. We recommend this because (in some cases) third-party apps will return to HPP in the default browser. Returning to HPP in the default browser breaks the flow (due to missing session data in the browser).

You can redirect back to your mobile app, at the end of the payment journey on HPP, using the redirect URL parameters (successURL, failureURL, and so on). Use a custom URL scheme to launch your app. Custom URLs must bewhite-listed in Designer.

Refer to the following custom URL scheme documents for more information: