Click here to search the entire website

Payment requests (Direct)

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

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. the order code must not have been used previously

  • 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

<submit>

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

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

  </order>

</submit>

Order element with orderCode attribute

Order details

description and amount

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="T0211010">

  <description>ORDER 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 child 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

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

<orderContent>

<! [CDATA [PLACE HTML CONTENT HERE]] >

</orderContent>

orderContent

Payment details

paymentDetails element

The <paymentDetails> element contains the details of the selected payment method.

Every payment method has its own set of elements and attributes. For the list of available payment methods, see payment method codes. Specifics of our alternative payment methods are also covered in the alternative payment methods guide. 

The <session> element (which contains the shopperIPAddress and id attributes) contains the shopper’s browser session information, which is required for 3D Secure transactions.

paymentDetails example

This example shows a card payment, where <CARD-SSL> (used for card payments) is the payment method code:

Select

<paymentDetails>

  <CARD-SSL>

    <cardNumber>4444333322221111</cardNumber>

    <expiryDate>

      <date month="01" year="2020"/>

    </expiryDate>

    <cardHolderName>J. Shopper</cardHolderName>

    <cardAddress>

      <address>

        <address1>47A</address1>

        <address2>Queensbridge Road</address2>

        <address3>Suburbia</address3>

        <postalCode>CB94BQ</postalCode>

        <city>Cambridge</city>

        <state>Cambridgeshire</state>

        <countryCode>GB</countryCode>

      </address>

    </cardAddress>

  </CARD-SSL>

  <session shopperIPAddress="123.123.123.123" id="0215ui8ib1" />

</paymentDetails>

paymentDetails: Visa test card payment

Email details

shopper element

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

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

Note:  If you're using 3DS authentication, there are some other elements you need to add to <shopper>. See here for details.

<shopper>

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

</shopper>

Shopper information

Flexible account variables

Prerequisite:  You have contacted us to enable flexible account variables processing for the required dynamic elements.

To streamline your integration with us, you can submit the below dynamic elements through the API. These all apply to Visa, Mastercard and Maestro payments. American Express payments can only make use of the dynamic MCC. JCB payments can only make use of dynamic 3DS.

Warning:  It is your responsibility to send the correct dynamic elements for each payment.

Dynamic MCC

If you have multiple merchant category codes, the <dynamicMCC> element lets you send a different merchant category code per transaction.

Dynamic interaction type

The type attribute of <dynamicInteractionType> lets you adapt the shopper interaction based on the method a transaction connects to Worldpay.

The values you can send are:

  • "ECOMMERCE" - For transactions through your website

  • "MOTO" - For mail or telephone orders

Dynamic 3DS

If you have Dynamic 3DS enabled, you can use the optional overrideAdvice attribute of <dynamic3DS> to override any preset rules.

Accepted values are:

  • "do3DS" - perform 3DS for this order. Ignore any configured rules

  • "no3DS" - do not perform 3DS for this order. Ignore any configured rules

Note:  You can also use overrideAdvice if you don't have rules set up.

Dynamic statement narrative

You can add certain fields to your narrative such as order code, description or ticket code. To learn more about dynamic statement narratives, contact your Implementation Manager.

Example Direct order

This example shows a complete order for the Direct 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"> <!--Enter a unique order code each time-->

      <description>YOUR DESCRIPTION</description> <!--Enter a description useful to you-->

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

      <paymentDetails>

        <CARD-SSL>

          <cardNumber>4444333322221111</cardNumber>

          <expiryDate><date month="01" year="2020"/></expiryDate>

          <cardHolderName>A Shopper</cardHolderName>

          <cardAddress>

            <address>

              <address1>47A</address1>

              <address2>Queensbridge Road</address2>

              <address3>Suburbia</address3>

              <postalCode>CB94BQ</postalCode>

              <city>Cambridge</city>

              <state>Cambridgeshire</state>

              <countryCode>GB</countryCode>

            </address>

          </cardAddress>

        </CARD-SSL>

        <session shopperIPAddress="123.123.123.123" id="0215ui8ib1"/>

      </paymentDetails>

      <shopper>

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

        <browser>

          <acceptHeader>text/html</acceptHeader>

          <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>

        </browser>

      </shopper>

      <dynamicMCC>5045</dynamicMCC> <!--The merchant category code that applies to this transaction-->

      <dynamicInteractionType type="ECOMMERCE"/> <!--The type of shopper interaction for this transaction-->

      <dynamic3DS overrideAdvice="do3DS"/> <!--Optional override element to ignore preset dynamic 3DS rules-->

    </order>

  </submit>

</paymentService>

Example Direct order

Responses to an order

When you send us a valid XML order with payment details, we send it on to the financial institutions (acquirers) for authorisation. The result of the authorisation request is reported to us as one of these:

  • AUTHORISED

  • REFUSED

  • ERROR

We then send an XML response back to your system about the payment status of the order.

Best practice:  HTTP timeout interval

The HTTP timeout interval is the length of time you choose to keep the HTTP connection open with us, while waiting for a response to an order. Our merchants tend to go for a timeout interval between 10 and 60 seconds.

If the interval is quite short (less than 5 seconds) then you could sometimes see an increase in the number of orders that get timed out. This can happen if our systems are very busy or the issuer response is slow. To help mitigate the effect of timeouts, we suggest showing a pending page to the shopper, and using our order notifications service to identify the payment outcome more quickly.

For more advice on the HTTP timeout interval that’s right for you, talk to your Implementation Manager.

For more information about the different payment statuses that a payment can be given during its life cycle, see Payment status definitions. For a list of payment status response codes, see Issuer response codes.

Example AUTHORISED reply message

We send an AUTHORISED reply message when the financial institution (acquirer) has approved the payment. An AUTHORISED response is a strong indication that the payment details that were submitted are valid, but it is not a guarantee of payment. For more information, see The Payment Process.

This example shows our reply after a payment has been successfully authorised:

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

      <payment>

        <paymentMethod>VISA-SSL</paymentMethod>

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

        <lastEvent>AUTHORISED</lastEvent>

        <AuthorisationId id=666"/>

        <balance accountType="IN_PROCESS_AUTHORISED">

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

        </balance>

        <cardNumber>4444********1111</cardNumber>

        <riskScore value="0"/>

      </payment>

    </orderStatus>

  </reply>

</paymentService>

AUTHORISED reply from Worldpay

Note:  For Visa and Mastercard cards, we also return the card sub-type. These are covered in payment method codes.

XML reference

Order elements

Elements/attributes

M/O

Description

<order>

    orderCode

Mandatory

The order code specified by you. Ideally no more than 20 for onward processing.

<description>

Mandatory

The order description specified by you.

 

<amount>

    currencyCode

Mandatory

Specifies the currency (ISO 4217) code for the relevant country. Must be upper case.

 

<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. Maximum value 2147483647.

cardNumber

Mandatory

Credit card number, Debit Card number, Purchase Card number, Bank account number, or any other applicable Bank Identifier.

Example “4459510002561039”

<expiryDate>

    month

Mandatory This returns the expiry date of a card; however, only for the AUTHORISED status and only when the paymentMethodDetail in XML response (and this element) has been enabled. Contact us to enable these.

<expiryDate>

    year

Mandatory
<cardHolderName> Mandatory

Account holder name on card or account.

Example “John Smith”

<address1> Mandatory Billing contact Address line 1
<address2> Optional Billing contact Address line 2
<address3> Optional Billing contact Address line 3
<postalCode> Mandatory

Billing contact ZIP / Postal Code.

Example “CB4 0WE”

<city> Mandatory Billing contact City
<state> Optional 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. Example “Cambridgeshire”.
<countryCode> Mandatory

Billing contact ISO Country Code. Must be upper case.

Example “GB”

For details, see ISO Country Codes.

<session>

       shopperIPAddress

Mandatory

Customer’s IP address.

Example “207.253.196.193”

<session>

       id

Mandatory  
<shopperEmailAddress> Mandatory

Billing contact 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.
<dynamicMCC> Optional Lets you send a different merchant category code per transaction. Contact us to enable.

<dynamicInteractionType>

    type

Optional Lets you adapt the shopper interaction based on the method a transaction connects to Worldpay. Values are "MOTO" and "ECOMMERCE". Contact us to enable.
<dynamic3DS>

    overrideAdvice

Optional Lets you override any preset dynamic 3DS rules. Values are "do3DS" and "no3DS".

Response elements

Elements/attributes

M/O

Description

<amount>

    currencyCode

Mandatory

Specifies the currency (ISO 4217) code for the relevant country. Must be upper case.

 

<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. Maximum value 2147483647.

<amount>

    debitCreditIndicator

Mandatory

Indicates that the amount is positive ("credit") or negative ("debit")

LastEvent Mandatory Specifies the latest payment status.
<AuthorisationId>

    id

Optional A reference your shoppers can use to identify a particular payment with their issuer.

<balance>

    accountType

Mandatory For AUTHORISED transactions, this will show as IN_PROCESS_AUTHORISED. For more information about the accountType values, see the payment process
<balance>

    amount value

Mandatory Specifies the total amount the shopper is expected to pay. Maximum value 2147483647.
<balance>

    currencyCode

Mandatory

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

 

<balance>

    exponent

Mandatory

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

<balance>

    debitCreditIndicator

Mandatory

Indicates that the amount is positive ("credit") or negative ("debit").

cardNumber

Mandatory The first and last four digits of the card number are returned in the cardNumber element.

riskScore

    value

Optional Shows the score that the Risk Management Service assigned to the authorisation request (“0"), if you have it.

To integrate Authentication, click here

To find out about the payment process, click here

To send orders in batches, click here