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

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, 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
Copied!
<submit>
    <order orderCode="YOUR_ORDER_CODE"> <!--Enter a unique order code each time-->
        <!--REMAINING ORDER INFORMATION GOES HERE-->
    </order>
</submit>

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

Copied!
<order orderCode="T0211010">
    <description>ORDER 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 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 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

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

Copied!
<orderContent>
    <! [CDATA [PLACE HTML CONTENT HERE]] >
</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, seepayment method codes. Specifics of our alternative payment methods are also covered in thealternative payment methodssection.

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:

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

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

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

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 haveDynamic 3DSenabled, 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 capture delay

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

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:

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"> <!--Enter a unique order code each time-->
         <description>YOURDESCRIPTION</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 3DSrules-->
      </order>
   </submit>
</paymentService>

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 ourorder notificationsservice 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, seeThe payment process. For a list of payment status response codes, seeAuthorisation 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, seeThe Payment Process.

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

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

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

XML reference

Order elements

Elements/attributesM/C/ODescription
<order>
orderCode
MandatoryThe order code specified by you. Ideally no more than 20 for onward processing.
<description>MandatoryThe order description specified by you.
<amount>
currencyCode
MandatorySpecifies the currency (ISO 4217) code for the relevant country. Must be upper case.
<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. Maximum value 2147483647.
cardNumberMandatoryCredit card number, Debit Card number, Purchase Card number, Bank account number, or any other applicable Bank Identifier.
Example “4459510002561039”
<expiryDate>
month
MandatoryThis 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>MandatoryAccount holder name on card or account.
Example “John Smith”
<address1>ConditionalBilling contact Address line 1 .
Optional unless <city> is supplied.
<address2>OptionalBilling contact Address line 2
<address3>OptionalBilling contact Address line 3
<postalCode>MandatoryBilling contact ZIP / Postal Code.
Example “CB4 0WE”
<city>ConditionalBilling contact City .
Optional unless <address1> is supplied.
<state>OptionalBilling 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>MandatoryBilling contact ISO Country Code. Must be upper case.
Example “GB”.
For details, seeISO Country Codes.
<session>
shopperIPAddress
MandatoryCustomer’s IP address.
Example: “207.253.196.193”
<session>
id
Mandatory
<shopperEmailAddress>MandatoryBilling contact 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.
<acceptHeader>OptionalMust contain exactly the same content as the HTTP user-agent header that was sent to you by the shopper’s user agent.
<userAgentHeader>OptionalLets you send a different merchant category code per transaction. Contact us to enable.
<dynamicMcc>
type
OptionalLets 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
OptionalLets you override any preset dynamic 3DS rules. Values are "do3DS" and "no3DS".

Response elements

Elements/attributesM/ODescription
<amount>
currencyCode
MandatorySpecifies the currency (ISO 4217) code for the relevant country. Must be upper case.
<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. Maximum value 2147483647.
<amount>
debitCreditIndicator
MandatoryIndicates that the amount is positive ("credit") or negative ("debit")
LastEventMandatorySpecifies the latest payment status.
<AuthorisationId>
id
OptionalA reference your shoppers can use to identify a particular payment with their issuer.
<balance>
accountType
MandatoryFor AUTHORISED transactions, this will show as IN_PROCESS_AUTHORISED. For more information about the accountType values, seethe payment process
<balance>
amount value
MandatorySpecifies the total amount the shopper is expected to pay. Maximum value 2147483647.
<balance>
currencyCode
MandatorySpecifies the currency (ISO 4217) code for the relevant country.
<balance>
exponent
MandatorySpecifies where the decimal point or comma should be placed in the value, counting from the right.
<balance>
debitCreditIndicator
MandatoryIndicates that the amount is positive ("credit") or negative ("debit").
cardNumberMandatoryThe first and last four digits of the card number are returned in the cardNumber element.
riskScore
value
OptionalShows the score that the Risk Management Service assigned to the authorisation request (“0"), if you have it.