- Home
- All APIs
- WPG guide
- About Hosted
- Payment page integration
Payment page integration
For each installationId
you have, you can specify a different integration type, a different set of parameters and a differentinstallationId
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
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
- 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 experienceMerchant-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 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: This parameter does not work with Apple Pay, Google Pay and the Pay by Bank App.
In the full-page integration you append this to the redirect URL:
&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. For
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 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/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 some<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 examplehttps://www.example.com/expiry.html |
HPP Session Error | errorURL | The 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" |
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
To ensure your custom result URLs are valid, follow these guidelines:
- A custom result URL must start with
http://
orhttps://
, unless you whitelist your own Custom URL. See thePayment Page Designer Guide for more information. - All URL parameters must be URL-encoded.
- A custom result URL can contain:
- Any host containing Latin alphanumeric characters,
.
(full stop) or-
(dash). For example:192.100.1.254
,www.example.com
- Top-level domains such as
.office
. Top-level domains are not validated - Port number (optional)
- URL fragments, provided the URL is URL-encoded. For example,
http://www.example.com#welcome
, when URL-encoded would appear as follows:http%3A%2F%2Fwww.example.com%23welcome
- URLs with one or more adjacent slashes. For example: www.example.com/new//home/info
- Internet Protocol version 4 (IPv4) domains
- Punycode URLs. For example:
http://xn--hxargifdar.idn.icann.org
- Any host containing Latin alphanumeric characters,
- A custom result URL cannot contain:
- User information. For example:
http://username:password@test.worldpay/home
- Internet Protocol version 4 (IPv6) domains
- Non-Latin URLs, even if they are encoded. For example:
http://عربي.امارات
andhttp%3A%2F%2F%D8%B9%D8%B1%D8%A8%D9%8A.%D8%A7%D9%85%D8%A7%D8%B1%D8%A7%D8%AA
- User information. For example:
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
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
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 use
Customising your payment pages
You can customise through the payment page designer. More information on how to do this can be found
Alternatively you can send individual custom options
with each transaction using the
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
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 be
Refer to the following custom URL scheme documents for more information: