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 toreference 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 referencehere, and it's downloadablehere.

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:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//Worldpay//DTD Worldpay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">

DTD version number and Merchant Code

The <paymentService> root element has two required attributes:

  • The version number of the Worldpay DTD
  • Yourmerchant code(which is always written in capitals)
Copied!
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE"> <!--Enter your own merchant code-->
    <submit>
    <!--YOUR ORDER INFORMATION-->
    </submit>
</paymentService>

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, or 25 characters if you are connecting to our US domestic acquiring platform (either way, 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. Yourintegration type,parametersandpayment page designare linked to each installationId you have.

Copied!
<submit>
    <order orderCode="YOUR_ORDER_CODE"> installationId="YOUR_INSTALLATION_ID">
        <!--REMAINING ORDER INFORMATION GOES HERE-->
    </order>
</submit>

captureDelay attribute

You can use the captureDelay attribute of <order> to set a capture delay per transaction:

Copied!
<order orderCode="YOUR_ORDER_CODE" captureDelay="0">

Capture delay values

ValueDescription
0Automatically captures immediately
1-14Sets the number of days to delay capture by
OFFDisables capture completely (you have to capture with anorder modification)
DEFAULTUses the default preconfigured value set on the merchantCode

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, seeISO currency codes):

Copied!
<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>

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 Worldpay fraud detection services 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 amodification 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 yourpaymentsorordersin theMAI, and can be used inemail notificationswhich 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:

Copied!
<orderContent>
    <! [CDATA [PLACE HTML ORDER DESCRIPTION HERE]] >
</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

    Warning: If you <exclude> available card types and then the shopper enters a PAN from an excluded card, the payment will fail and you will not get an error.

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"

Best practice: To allow only one card payment method, we recommend that you instead use thepreferredPaymentMethodattribute. If you restrict card types via the <paymentMethodMask>, shoppers entering a restricted card number will not be able to complete their order.

exclude element

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

Copied!
<paymentMethodMask>
    <include code="ALL"/>
    <exclude code="AMEX-SSL"/>
</paymentMethodMask>

You can use different payment method masks for different orders. You can also bypass the payment method selection page by specifying thepreferred payment method, includingalternative payment methods.

Note:

  • When using tokenisation with our Hosted Payment Pages, additional elements need to be applied in the XML. SeeStored CredentialsandTokenisationfor details.
  • If you are setup for3DS2and are sending tokenised payments, 3DS2 is applied.

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

Copied!
<shopper>
    <shopperEmailAddress>jshopper@myprovider.com</shopperEmailAddress>
</shopper>

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 thePayment Page Designer.

Example Hosted order

This example shows an order for the Hosted model:

Copied!
<?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[AMOREDETAILEDDESCRIPTIONOFYOURORDERCONTENTCANGOHERE]]></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>

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&Ticket=00146321872957902pqKhCTUf0vajKCw-X5HqZA

Note: We do not send the 3D Secure Authentication (3DS) result in our response. If you want to see this, enableorder notifications.

Example response

Copied!
<?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>

The id attribute of <reference> can be used as a payment reference if the shopper is expected to make a payment with an off-line payment method (like a bank transfer).

If you are sending the order solely to acquire this reference id, there's no need to use the redirection URL and redirect the shopper. Shoppers who have paid for an order using an off-line payment method sometimes refer to this number instead of the order code.

Note: For Swedish bank transfers you need to run some calculations to apply a final check digit to the reference id. For more information contact your Implementation Manager.

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 inPayment page integration.

XML reference

Order elements

Elements/attributesM/ODescription
<order>
orderCode
MandatoryThe order code specified by you.
<order>
InstallationId
MandatoryContains the identification code for your custom Hosted Payment Page configuration.
<orderContent>OptionalContains a more detailed description of the products or services that make up the order.
<description>MandatoryThe order description specified by you.
<amount>
currencyCode
MandatorySpecifies the currency (ISO 4217) code for the relevant country.
<amount>
exponent
MandatorySpecifies where the decimal point or comma should be placed in the value, counting from the right.
<amount>
value
MandatorySpecifies the total amount the shopper is expected to pay.
<include>
code
MandatorySeepaymentMethodMask elementfor details.
<exclude>
code
OptionalSeepaymentMethodMask elementfor details.
<shopperEmailAddress>MandatoryShopper email address.
<acceptHeader>OptionalMust contain exactly the same content as the HTTP accept header that was sent to you by the shopper’s user agent.
<userAgentHeader>OptionalMust contain exactly the same content as the HTTP user-agent header that was sent to you by the shopper’s user agent.
<firstName>OptionalShipping/Billing contact First Name
<lastName>OptionalShipping/Billing contact Last Name
<address1>MandatoryShipping/Billing contact Address line 1
<address2>OptionalShipping/Billing contact Address line 2
<address3>OptionalShipping/Billing contact Address line 3
<postalCode>MandatoryShipping/Billing contact ZIP / Postal Code.
Example:CB4 0WE
<city>MandatoryShipping/Billing contact City
<state>OptionalShipping/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>MandatoryShipping/Billing contact ISO Country Code
Example:GB
For details, seeISO Country Codes.

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