Click here to search the entire website

Payment page integration

For each installationId you have, you can specify a different integration type, a different set of parameters and a different Hosted 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 take Alternative 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 SDK is 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 a customOptions object 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:  If you specify a preferred payment method, the shopper can't select a language and country on the first payment method selection page. For alternative payment methods, you need to set the correct Country Code parameter 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, see Supported Languages.

  • The country parameter influences which of the available payment methods are presented to the shopper. For example, if you set the country code as "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

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

or

SENT_FOR_AUTHORISATION

pendingURL

The URL to redirect the shopper to if the AUTHORISED result isn't immediately known (which happens with some Alternative Payment Methods). For example: www.example.com/pending.html

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

Full-page: append "&failureURL=http%3A%2F%2Fwww.example.com%2Ffailure.php"

CANCELLED

Note:  In this case 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"

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"

 

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 the Payment 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 the Payment 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

  • 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 use notifications instead. Notifications are a reliable way of updating the status of payments in your back-office system.

To customise your payment page design, click here

If you are doing a JavaScript SDK integration, click here

To make some final checks before going live, click here