Click here to search the entire website

Payment requests (Hosted)

The starting point for all interaction with Worldpay. Each element is shown in the order it must appear in the payment request.

On this page:

Jump to reference table.

The Worldpay DTD

The Worldpay DTD provides all the XML elements that you need for communicating with the Worldpay payment service and third party processors. It's available to view and reference here, and it's downloadable here.

Store the DTD on your own system rather than calling it up from Worldpay, and update it regularly.

XML and DTD declarations

Valid XML files begin like this:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE paymentService PUBLIC "-//Worldpay//DTD Worldpay PaymentService v1//EN"

  "http://dtd.worldpay.com/paymentService_v1.dtd">

XML and DTD declaration

DTD version number and Merchant Code

The <paymentService> root element has two required attributes:

  • The version number of the Worldpay DTD

  • Your merchant code (which is always written in capitals)

<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE"> <!--Enter your own merchant code-->

<submit>

    <!--YOUR ORDER INFORMATION-->

</submit>

</paymentService>

DTD version and Merchant Code

The order element

The <order> element is:

  • Found within the <submit> element

  • Has a required attribute orderCode, and

  • Must contain the installationId attribute

It describes what the shopper is ordering, and includes their payment details, payment method details, shipping address and billing address.

orderCode attribute

The orderCode attribute:

  • Must have a unique value - i.e. not a previously used order code

  • Can be up to 64 characters in length (we recommend a minimum of 9 and a maximum of 20 for onward processing). Spaces, quotation marks, code brackets (< and >) and pipes ("|"), are not allowed

installationId attribute

The installationId attribute contains the identification code for your custom Hosted Payment Page configuration. Your integration type, parameters and payment page design are linked to each installationId you have.

<submit>

    <order orderCode="YOUR_ORDER_CODE"> installationId="YOUR_INSTALLATION_ID">

      <!--REMAINING ORDER INFORMATION GOES HERE-->

    </order>

</submit>

Use of installation id

Order details

description and amount elements

The <description> and <amount> child elements are used like this (for a list of currency codes and their respective exponents, see ISO currency codes):

<order orderCode="YOUR_ORDER_CODE"> <!--Enter a unique order code each time-->

  <description>YOUR_DESCRIPTION</description> <!--Enter a description useful to you-->

  <amount currencyCode="GBP" exponent="2" value="5000"/>

</order>

Description and amount

Using value for account verification

Prerequisite:  You've contacted us to enable account verification.

You can confirm the validity of a card by submitting a value of "0". AVS, CVC, 3DS, and checks made by Risk Management Module and RiskGuardian are supported.

Visa, Mastercard (including Maestro) and American Express cards support zero value account verifications. For all other cards you'll need to submit a nominal amount and then cancel the transaction using a modification request. To learn more about account verification, contact your Implementation Manager.

orderContent element (optional)

The <orderContent> element can contain a more detailed description of purchased products/services, supplied in HTML format. Order content can be viewed in your payments or orders in the MAI, and can be used in email notifications which we can send to the shopper on your behalf.

When supplying HTML order content:

  • You must use valid HTML tags

  • You cannot use scripting

  • Your HTML content will be screened against a whitelist, and any content not included in the whitelist will be removed

Note:  <orderContent> is not displayed on your Hosted Payment Pages.

Always place the order content in a CDATA section to avoid parsing problems:

<orderContent>

<! [CDATA [PLACE HTML ORDER DESCRIPTION HERE]] >

</orderContent>

orderContent

Payment details

paymentMethodMask element

The <paymentMethodMask> element:

  • Limits the available payment methods to be shown to the shopper

  • Must contain at least one <include> element

  • Can optionally contain the <exclude> element

include element

You can specify a separate <include> element for every payment method available on your account. Alternatively you can include:

  • All the available payment methods by using an <include> element with the payment method code "ALL"

  • Only card payment methods by using an include element with the payment method code "ONLINE"

exclude element

Use the optional <exclude> element to exclude a particular payment method. This example shows all available payment methods offered, except American Express:

<paymentMethodMask>

  <include code="ALL"/>

  <exclude code="AMEX-SSL"/>

</paymentMethodMask>

Use of include/exclude

You can use different payment method masks for different orders. You can also bypass the payment method selection page by specifying the preferred payment method, including alternative payment methods.

Email details

shopper element

The <shopper> element contains more information about the cardholder making the payment.

It includes <shopperEmailAddress>, which we can use to send an email to the shopper when the payment is authorised or refused (if you choose to enable this notification channel).

<shopper>

  <shopperEmailAddress>jshopper@myprovider.com</shopperEmailAddress>

</shopper>

Shopper information

shippingAddress and billingAddress

You use <billingAddress> to pre-populate the billing address fields on the Worldpay payment pages. If you also want to specify a separate delivery address, also use <shippingAddress>.

Shoppers changing the address information

Shoppers can change the pre-populated address on the Worldpay payment pages. The address on the payment pages may not always be the same details that:

  • Worldpay uses for fraud-screening checks, such as AVS (address verification service)

  • Your system recorded as the billing address for the order

Hiding the address fields on the payment pages

You can hide the address fields to stop the shopper from changing this information. To find out how to do this, see the Payment Page Designer.

Example Hosted order

This example shows an order for the Hosted model:

Select

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE paymentService PUBLIC "-//Worldpay//DTD Worldpay PaymentService v1//EN"

  "http://dtd.worldpay.com/paymentService_v1.dtd">

<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE"> <!--Enter your own merchant code-->

  <submit>

    <order orderCode="YOUR_ORDER_CODE" installationId="1234567"> <!--installationId identifies your Hosted Payment Page-->

      <description>YOUR_DESCRIPTION</description> <!--Enter a description useful to you-->

      <amount currencyCode="GBP" exponent="2" value="5000"/>

      <orderContent>

        <![CDATA[A MORE DETAILED DESCRIPTION OF YOUR ORDER CONTENT CAN GO HERE]]>

      </orderContent>

      <paymentMethodMask>

        <include code="ALL"/>

      </paymentMethodMask>

      <shopper>

        <shopperEmailAddress>jshopper@myprovider.com</shopperEmailAddress>

      </shopper>

      <shippingAddress>

        <address>

          <address1>47A</address1>

          <address2>Queensbridge Road</address2>

          <address3>Suburbia</address3>

          <postalCode>CB94BQ</postalCode>

          <city>Cambridge</city>

          <state>Cambridgeshire</state>

          <countryCode>GB</countryCode>

        </address>

      </shippingAddress>

      <billingAddress>

        <address>

          <address1>47A</address1>

          <address2>Queensbridge Road</address2>

          <address3>Suburbia</address3>

          <postalCode>CB94BQ</postalCode>

          <city>Cambridge</city>

          <state>Cambridgeshire</state>

          <countryCode>GB</countryCode>

        </address>

      </billingAddress>

    </order>

  </submit>

</paymentService>

Example Hosted order

Our response

When we've received a valid order we send an XML response, which includes the URL (in <reference>) to redirect the shopper to the Worldpay Hosted Payment Pages. It has to be parsed by your system. If the shopper was redirected in the test environment, the example redirect URL would be:

https://payments-test.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=NGPPTESTMERCH1%5Ejsxml3835829684&amp;Ticket=00146321872957902pqKhCTUf0vajKCw-X5HqZA

Example response

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE paymentService PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//EN"

  "http://dtd.worldpay.com/paymentService_v1.dtd">

<paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the order-->

  <reply>

    <orderStatus orderCode="ExampleOrder1"> <!--The orderCode you supplied in the order-->

      <reference id="YourReference">https://payments-test.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=NGPPTESTMERCH1%5Ejsxml3835829684&amp;Ticket=00146321872957902pqKhCTUf0vajKCw-X5HqZA</reference>

    </orderStatus>

  </reply>

</paymentService>

Example response

Redirection time limit

Orders received by Worldpay are available for a maximum period of three days, so once you have the URL the shopper must be redirected to their payment details during this period.

Best practice:  Incomplete payments - if a shopper does not complete the process of selecting a payment method and supplying the required payment details, the order does not obtain a payment status; however, the order will be visible in the Merchant Administration Interface (MAI). Your back-office system(s) might want to interpret these orders without a payment status correctly.

What happens next

This depends on your integration type to the Worldpay Hosted Payment Pages:

  • In the full-page redirect integration, you append parameters to the redirect URL

  • In the JavaScript SDK integration, you instead use a customOptions object to define these parameters

This is explained more in Payment page integration.

XML reference

Order elements

Elements/attributes

M/O

Description

<order>

    orderCode

Mandatory

The order code specified by you.

<order>

    InstallationId

Mandatory Contains the identification code for your custom Hosted Payment Page configuration.
<orderContent> Optional Contains a more detailed description of the products or services that make up the order.

<description>

Mandatory

The order description specified by you.

 

<amount>

    currencyCode

Mandatory

Specifies the currency (ISO 4217) code for the relevant country.

 

<amount>

    exponent

Mandatory

Specifies where the decimal point or comma should be placed in the value, counting from the right.

<amount>

    value

Mandatory

Specifies the total amount the shopper is expected to pay.

<include>

    code

Mandatory See paymentMethodMask element for details.
<exclude>

    code

Optional See paymentMethodMask element for details.
<shopperEmailAddress> Mandatory

Shopper email address.

<acceptHeader> Optional Must contain exactly the same content as the HTTP accept header that was sent to you by the shopper’s user agent.
<userAgentHeader> Optional Must contain exactly the same content as the HTTP user-agent header that was sent to you by the shopper’s user agent.
<firstName> Optional Shipping/Billing contact First Name
<lastName> Optional Shipping/Billing contact Last Name
<address1> Mandatory Shipping/Billing contact Address line 1
<address2> Optional Shipping/Billing contact Address line 2
<address3> Optional Shipping/Billing contact Address line 3
<postalCode> Mandatory

Shipping/Billing contact ZIP / Postal Code.

Example “CB4 0WE”

<city> Mandatory Shipping/Billing contact City
<state> Optional

Shipping/Billing contact state code, two-character long ISO code required for North America. Remaining Region and Provinces around the world may use free form field, such as “Cambridgeshire”.

<countryCode> Mandatory

Shipping/Billing contact ISO Country Code.

Example “GB”

For details, see ISO Country Codes.

Securing payments