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- These parameters help to improve the shoppers' payment experience
Merchant-defined parameters- These parameters provide information specific to your business

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.

In the full-page integration you append this to the redirect URL:

Copied!

&preferredPaymentMethod=VISA-SSL

Note: If you specify a preferred payment method, the shopper can't select a language and country on the first payment method selection page. Foralternative payment methods, you need to set the correctCountry Codeparameter as well. For example, IDEAL-SSL will only work if 'NL' is passed as the Country Code.

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/outcome	Parameter	Description / Comments
AUTHORISED	successURL	The 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_AUTHORISATION	pendingURL	The 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"
REFUSED	failureURL	The 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 shopper	cancelURL	The 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"`
Expired	expiryURL	The URL to redirect the shopper when the HPP session expires. For example`https://www.example.com/expiry.html`
ERROR	errorURL	The URL to redirect the shopper when there is an unrecoverable error during payment processing. For example: `https//www.example.com/error.html` Full-page: append `"&errorURL=http%3A%2F%2Fwww.example.com%2Ferror.php"`

Copied!

https://secure.worldpay.com/jsp/shopper/SelectPaymentMethod.jsp?orderKey=MYMERCHANT^T0211010&country=GB&language=en&successURL=http%3A%2F%2Fwww.webshops.int.com%2Fsuccess.asp&failureURL=http%3A%2F%2Fwww.webshops.int%2Ffailure.php&pendingURL=http%3A%2F%2Fwww.webshops.int%2Fpending.html&cancelURL=http%3A%2F%2Fwww.webshops.int%2Fcancel.html&preferredPaymentMethod=VISA-SSL

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.

Going live checklist