You can specify the following parameters during the payment process:
The parameters you specify apply to one installation ID.
For each order you send to us, you can specify the following types of parameters:
- Worldpay parameters - These parameters help to improve the customer payment experience.
- Merchant-defined parameters - These parameters provide information that is specific to your business.
Specifying Worldpay parameters can improve your customers' payment experience.
The method for specifying Worldpay parameters depends on your integration type.
- Full-page redirect - Append Worldpay parameters to the redirect URL that we send you. We send you a redirect URL for every valid XML order we receive from you.
For more information, see Hosted Integration in the Worldwide Payment Gateway Integration Guide.
- iframe or lightbox - Specify Worldpay parameters in the properties for the customObject object.
For more information about integrating using an iframe or lightbox, see iframe or lightbox set up.
For each order you submit to us, we recommend that you specify one or more of the following Worldpay parameters:
Providing custom result URLs ensures that your customers 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.
You can provide the following result URLs:
- Success URL The URL to redirect the shopper to when the payment is successfully completed. For example: https://www.example.com/success.html
- Cancel URL The URL to redirect the shopper to when the payment is cancelled. For example: https://www.example.com/cancel.html
- Pending URL The URL to redirect the shopper to if a pending payment status is returned. For example: www.example.com/pending.html
- Failure URL The URL to redirect the shopper to if the payment fails. For example: www.example.com/failure.html
- Error URL The URL to redirect the shopper when there is an unrecoverable error during payment processing. For example: https//www.example.com/error.html
Validation rules for custom result URLs
To ensure your custom result URLs are valid, follow these guidelines:
- A custom result URL must start with http:// or https://
- All URL parameters must be URL-encoded.
- A custom result URL can contain the following:
- Any host containing Latin alphanumeric characters, . (full stop) or - (dash). For example: 184.108.40.206, www.example.com
- Top-level domains such as .office. Top-level domains are not validated.
- Port number (optional).
- For full-page redirect only: 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
- A custom result URL cannot contain the following:
- User information. For example: http://username:email@example.com/home
- Internet Protocol version 4 (IPv6) domains.
- Non-Latin URLs, even if they are encoded. For example: http://عربي.امارات and http%3A%2F%2F%D8%B9%D8%B1%D8%A8%D9%8A.%D8%A7%D9%85%D8%A7%D8%B1%D8%A7%D8%AA
Providing your customer's payment method means your customer doesn't need to specify it later in the payment process. Instead, your customer is immediately redirected to the payment page where they can enter credit card or other payment data.
You can improve your customer's payment experience by specifying values for the following parameters:
- Preferred language. When you provide your customer's preferred language, text originating from Worldpay is displayed in the specified language on the Hosted Payment Pages. We do not translate the order description or order content that you provide. For a list of supported languages, see Supported languages.
- Country code. By specifying a country code, you can limit the number of payment methods that are displayed to your customer on the payment pages. For example, if you specify the country code for France, your customer would see only those payment methods available for France. If you don't specify a country code or a preferred payment method, all payment methods worldwide for which you are eligible are displayed.
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.
Specifying merchant-defined parameters
Before you can use custom parameters, you must specify them in the Extra URL parameters field in the Payment Page Designer.
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. Custom append parameters are specific to an installation ID.
For more information about the Payment Page Designer, see Payment Page Designer.
To inform your customers about the result of a payment, we redirect them to a result URL. By default, the result URL that we use does not contain any appended parameters. However, you can request to have a basic set of parameters appended to the result URL. These parameters are provided for your information only. The option to receive these parameters is specific to an installation ID.
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, the following parameters are appended to the result URL:
- Order key
- Payment status
- Payment amount
- Payment currency
- Method authentication code (MAC)
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. For more information about notifications, see Order Notifications in the Worldwide Payment Gateway Integration Guide..