Plan your order submission | Specify parameters

Specify parameters

You can specify the following parameters during the payment process:

The parameters you specify apply to one installation ID.

Sending parameters

For each order you send to us, you can specify the following types of parameters:

Worldpay parameters

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:

Custom result URLs

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 URLClosed The URL to redirect the shopper to when the payment is successfully completed. For example: https://www.example.com/success.html
  • Cancel URLClosed The URL to redirect the shopper to when the payment is cancelled. For example: https://www.example.com/cancel.html
  • Pending URLClosed The URL to redirect the shopper to if a pending payment status is returned. For example: www.example.com/pending.html
  • Failure URLClosed The URL to redirect the shopper to if the payment fails. For example: www.example.com/failure.html
  • Error URLClosed 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: 192.100.1.254, 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:password@test.worldpay/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

Shopper's payment method

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.

For more information on how to specify the preferred payment method see Redirecting to the Payment Pages in the Worldwide Payment Gateway Integration Guide.

Language and country code for the shopper

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.

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.

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.

Receiving parameters

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..