XML Redirect Integration Guide

Transcription

1 Corporate Gateway XML Redirect Integration Guide V6.0 November 2015 Use this guide to: Integrate with the payment services Create and test XML Redirect orders Implement and test 3D Secure Look up ISO codes, payment method codes, and more

2 XML Redirect Integration Guide > Contents Contents 1 Introduction What is XML Redirect? Who is this guide for? Skills and knowledge More help? Legal 6 2 Overview About XML Why XML Redirect? What you do What Worldpay does How does XML Direct compare? Types of payment pages for the XML Redirect model Securing payments in the XML Redirect model Displaying the standard payment pages using an iframe Payment Card Industry Data Security Standard (PCI DSS) D Secure authentication MCC 6012 Merchants, VISA and FuturePay/Regular Payments 12 3 Integrating with Worldpay Use HTTPS to Connect Error Code 4 Security error Creating and submitting valid XML messages Worldpay DTD (Document Type Definition) Valid XML 16 4 Structure of an XML Redirect order XML and DTD declarations DTD version number and Merchant code The order element ordercode attribute installationid attribute description and amount 20

3 XML Redirect Integration Guide > Contents ordercontent child element paymentmethodmask child element Shopper child element shippingaddress and billingaddress statementnarrative Example XML Redirect order Important Information for MCC 6012 Merchants Information to Collect MCC 6012 Technical Information FuturePay Payments and Regular Payment Agreements 29 5 Redirecting to the payment pages Redirecting the shopper Reference id attribute V.me by Visa and MasterPass payments Performing the redirection Customising the payment method selection pages Appending the Redirect URL country and language attributes bodyattr fontattr Result URLs preferredpaymentmethod Redirect URL: full example 35 6 Reporting results to the shopper Result URL Offline payment methods Payment results Example redirect URL Transaction status in the pendingurl HTTPS proxy HTTPS proxy restrictions Notifying the shopper by Securing the payment status About the MAC Creating and adding the MAC Receiving the signed redirect message 40

4 XML Redirect Integration Guide > Contents Calculating the MAC Setting the MAC secret 42 8 Testing in the XML Redirect model Test environment Differences between the test and production environments Test values Test credit and debit card numbers Testing captures and refunds Testing 3D Secure orders 44 Appendix A: Payment method codes 46 Credit and debit cards 46 Online debit methods 47 Offline payment methods 47 Online Alternative Payment Methods (APMs) 48 Appendix B: ISO currency codes 50 ISO currency codes 50 Appendix C: ISO country codes 52 Appendix D: Acquirer response codes 53 ISO 8583 response codes 53 Appendix E: CVC/CVV and AVS 55 Testing CVC/CVV 55 Testing AVS 55 Appendix F: Test card numbers 57 Test card numbers 57 Appendix G: XML error codes 58 Example: Error code 1. Internal error, a general error 58 Example: Error code 2. Parse error, invalid XML 58 Example: Error Code 4. Security error 59 Example: Error Code 5. Invalid request 60 Example: Error Code 7. Payment details in the order element are incorrect 60 Example: Error Code 7. Connection to V.me by Visa failed 60 Appendix H: Changes to the guide 62

5 XML Redirect Integration Guide > 1 Introduction 5 1 Introduction The XML Redirect Integration Guide describes how to integrate your payment platform with our payment gateway using the XML Redirect model. This guide shows you how to: Create, validate and submit XML orders. Redirect a shopper from your website to the Worldpay payment pages. Test your integration with Worldpay. Know the responses you can expect to receive from Worldpay s payment gateway. Implement 3D Secure fraud prevention in the XML Redirect model. It also includes a range of reference materials, including test card numbers, in the Appendices at the end of this guide. For important, high level technical guidance about your XML integration, on everything from the Worldpay DTD to cookies, see our Best Practice Guide at What is XML Redirect? Use XML Redirect if you do not want to collect and store shoppers payment details or details of the payment method that shoppers choose. Instead you redirect your shoppers to the Worldpay payment pages. A redirect integration means: That shoppers select their payment method and enter their payment details on Worldpay s secure payment pages, not your website. Your integration with Worldpay s payment gateway is faster, simpler and cheaper. For an overview of how the XML Redirect model works, see Overview on page 7. To help you create, test and manage your XML orders, this guide also provides you with a range of reference materials, including test card numbers. For more information, see the appendices at the end of this guide. 1.2 Who is this guide for? This is a technical integration guide, aimed at: System integrators. Other technical roles, including managers, who design and manage your payments solution Skills and knowledge To carry out the tasks described in this guide, you need the following skills and knowledge: XML programming skills. Knowledge of HTTPS.

6 XML Redirect Integration Guide > 1 Introduction 6 Basic knowledge of the Worldpay payment services. For more information about Worldpay s payment service, including payment methods, see the Worldpay website at More help? For more information about our products and services, including payment methods: See our website at Talk to your dedicated Relationship Manager (RM) For the Best Practice Guide, see For technical guides and developer resources see: To contact Corporate Support: 1.4 Legal corporatesupport@worldpay.com Phone: +44 (0) Worldpay All rights reserved. This document and its content are proprietary to Worldpay and may not be reproduced, published or resold. The information is provided on an "AS IS" basis for information purposes only and Worldpay makes no warranties of any kind including in relation to the content or sustainability. Terms and Conditions apply to all our services. Worldpay (UK) Limited (Company No / FCA No ), Worldpay Limited (Company No / FCA No ), Worldpay AP Limited (Company No / FCA No ). Registered Office: The Walbrook Building, 25 Walbrook, London EC4N 8AF and authorised by the Financial Conduct Authority under the Payment Service Regulations 2009 for the provision of payment services. Worldpay (UK) Limited is authorised and regulated by the Financial Conduct Authority for consumer credit activities. Worldpay, the logo and any associated brand names are all trade marks of the Worldpay group of companies.

7 XML Redirect Integration Guide > 2 Overview 7 2 Overview This chapter provides an overview of the XML Redirect model of integration with Worldpay s payment service. It describes: Why you would choose the XML Redirect model to integrate with Worldpay. How payments are processed through Worldpay (payment flow), using the XML Redirect model. How the security of payments is protected, through the PCI DSS security initiative and 3D Secure authentication. 2.1 About XML XML Redirect is an XML-based integration method. Figure 1: XML Redirect model XML (Extensible Markup Language) is a universal way of exchanging data across applications and platforms. Worldpay uses XML to send encrypted messages about payments between your system and our payment service over the Internet. To learn more about XML, go to Why XML Redirect? In the XML Redirect model, you redirect shoppers from your website to the Worldpay payment pages to complete their payments. The shopper selects the payment method and enters the mandatory payment details on the Worldpay payment pages. As well as processing payments, Worldpay: Validates the data entered by the shopper. Ensures that the data is held and disposed of securely.

8 XML Redirect Integration Guide > 2 Overview 8 You may want to use this model if you want to add complexity (such as handling mandatory payment data) to your own systems. For an illustration of the XML Redirect model see XML Redirect model on the previous page What you do In the XML Redirect model, you: 1. Collect details of the items that the shopper wants to purchase. 2. Send the XML order to Worldpay. 3. Display the result of the transaction to the shopper on your website. 4. Notify ( ) the shopper with the result of the transaction. We recommend that you ask your shoppers to have cookies enabled this may stop criminals who attempt to record the shopper s session and misuse it What Worldpay does In the XML Redirect model, Worldpay: 1. Captures the shopper s selected payment method and order details. 2. Redirects the shopper to Worldpay s payment pages. 3. Processes the shopper s payment order. 4. Carries out any change requests from the merchant (for example, to refund or cancel the order). 5. Responds to queries about the status of the order from the merchant (for example, to find out if the order has been Authorised, Captured or Settled) How does XML Direct compare? In the XML Direct model, you collect the shopper s payment details and selected payment method on your own platform, before processing the payment through Worldpay. A direct integration means that: Your shoppers make their payment on your website, instead of being redirected to the Worldpay payment pages. You keep full control of the payment process, including the payment pages that are displayed to shoppers. You may want to choose this model if you want to manage more of the of the shopper journey within your own environment. For more information about the XML Direct model, see the XML Direct Integration Guide. A major focus for PCI DSS (Payment Card Industry Data Security Standard) is the technology that is used to collect, store and process card data. This makes PCI DSS compliance particularly important if you are operating the XML Direct model, where you collect and store payment details on your own system.

9 XML Redirect Integration Guide > 2 Overview Types of payment pages for the XML Redirect model For the XML Redirect model, you can integrate using one of the following payment page types: Standard payment pages Hosted Payment Pages If you are new to Worldpay, we recommend integrating with the Hosted Payment Pages. The Hosted Payment Pages give your customers greater flexibility in the devices they can use to make payments. If you are an existing Worldpay customer, we recommend migrating to the Hosted Payment Pages. Standard payment pages Designed for desktop viewing, our standard payment pages make paying secure and easy. You can customise the appearance of the payment pages using HTML. Hosted Payment Pages With the Hosted Payment Pages, your customers can make payments from smartphones, tablets, PCs and other devices. The Hosted Payment Pages automatically adapt to the size and orientation of the device used. The adaptability of our payment pages eliminates the need for you to integrate for different devices. You only integrate once. The Hosted Payment Pages come standard with a clean, modern design that you can uses straight 'out of the box'. Or, you can add your own branding to the payment pages by updating our public cascading style sheet (CSS). We offer two ways to integrate the Hosted Payment Pages: Full-page redirect With a full-page redirect integration, the Hosted Payment Pages are displayed full page in a browser. When you redirect your customers to the Hosted Payment Pages, their webpage changes from your website to the Hosted Payment Pages. iframe or lightbox With an iframe or lightbox integration, the Hosted Payment Pages are displayed in an iframe or lightbox within your website. When you redirect your customer to the payment pages, the URL for your website remains unchanged, increasing shopper confidence and providing a more seamless shopping experience. An iframe or lightbox integration requires a more advanced integration. Currently only card payments are supported for an iframe or lightbox integration.

10 XML Redirect Integration Guide > 2 Overview 10 The following table compares features between the different types of payment pages: Type Description Standard payment pages Optimised for desktops. Hosted Payment Pages Full-page redirect Automatically optimises payment page content for a variety of devices. iframe or lightbox Automatically optimises payment page content for a variety of devices. Embeds the payment pages in an iframe or lightbox in your website. Level of integration required Standard Standard Advanced Payment types accepted Card and alternative payment methods (APMs) Card and alternative payment methods (APMs) Shopper's use of JavaScript Optional Optional Required Table 1: XML Redirect integration types For more information, see the Hosted Payment Pages Guide. 2.3 Securing payments in the XML Redirect model Currently supports card payment methods only. To collect and store payment information, such as card numbers and cardholder names, your system must fully comply with the Payment Card Industry Data Security Standard (PCI DSS). You may also want to implement 3D Secure authentication, which should reduce your exposure to fraud and increase confidence in online shopping Displaying the standard payment pages using an iframe To display our payment pages using an iframe, we recommend that you use the Hosted Payment Pages. Because of possible security issues, we do not support the use of HTML iframes with our standard payment pages. However, if you decide to use the standard payment pages with an iframe, you must: 1. Contact the Worldpay support team and inform them that you use iframes with the WorldPay payment page. 2. Accept that the security liability is yours; use the correct security technology to secure the pages with iframes. The security technology must ensure that the page into which the iframe is injected does not interfere with any contents or events in the Worldpay page. The cost involved in implementing the appropriate security measures for PCI DSS compliance means that the XML Direct model is only suitable if you have consistent high transaction For more information, please contact your Relationship Manager.

11 XML Redirect Integration Guide > 2 Overview 11 For more information about displaying the Hosted Payment Pages using an iframe, see the Hosted Payment Pages Guide Payment Card Industry Data Security Standard (PCI DSS) The Payment Card Industry Data Security Standard (PCI DSS) is a Global Card Scheme initiative. It aims to ensure that every entity that handles, stores or processes cardholder data does so in a secure way. PCI DSS: Combines the security standards for cardholder data at MasterCard and Visa. Is endorsed by American Express, JCB and Diners Club. In the XML Redirect model, Worldpay is principally responsible for the collection, storage and processing of cardholder data. This helps to reduce your costs for implementing the security measures needed for full PCI DSS compliance. For more information about PCI DSS, including its hardware and software standards, see the PCI Security Standards website at To help you comply with PCI DSS, the PCI Security Standards website also lists PCI-approved Quality Security Assessors (QSAs), who can advise on your system s security (a chargeable service). Worldpay is not responsible for the content or operation of external websites D Secure authentication 3D Secure is an authentication scheme for online credit and debit card transactions. The scheme is designed to: Help reduce your exposure to fraud. Increase confidence in online shopping through an additional level of authentication. The benefits of implementing 3D Secure include a shift in liability in the event of fraudulent transactions. The additional security benefits and liability shifts of authenticated transactions are currently only supported by Visa, MasterCard, and American Express SafeKey. 3D Secure implementations are branded to the relevant card scheme and card issuer: Card scheme Visa MasterCard American Express (UK and Singapore only) 3D Secure implementation Verified by Visa MasterCard SecureCode American Express SafeKey Table 2: Card scheme implementations of 3D Secure

12 XML Redirect Integration Guide > 2 Overview 12 Figure 2: 3D Secure authentication 3D Secure is currently limited to Internet payments, and does not cover: Fax, mail, or phone orders. All card types. 3D Secure authentication is mandatory for Maestro payments. MasterCard only allows merchants to accept Maestro payments if they implement 3D Secure MCC 6012 Merchants, VISA and FuturePay/Regular Payments From 1 June 2014, you must send us extra information for domestic payments processed in the United Kingdom under MCC (Merchant Category Code) MCC 6012 covers a range of payments for financial services. Examples of this type of payment include paying off all or part of a balance on a credit card or loan, or repayment of a mortgage. This change applies even if you have additional merchant codes as well as MCC This change also affects FuturePay payments because shoppers may use VISA to make their FuturePay payments. Merchants assigned the code MCC 6012 must collect the following information for each UK domestic VISA transaction. The information is the primary recipient s: Account Number/Primary Account Number (PAN) Last name (family name) Date of Birth (D.O.B) Postcode Primary recipients are the entities (people or organisations) that have a direct relationship with the financial institution. Also, these primary recipients have agreed to the terms and conditions of the financial institution. For more details of this requirement, see Important Information for MCC 6012 Merchants on page 25.

13 XML Redirect Integration Guide > 2 Overview 13 You can also find high level information about the MCC 6012 requirement in the Best Practice Guide by going to Failure to comply may cause VISA to fine you.

14 XML Redirect Integration Guide > 3 Integrating with Worldpay 14 3 Integrating with Worldpay This chapter outlines the major tasks that you must carry out to integrate your website with Worldpay s payment service, using the XML Redirect model. These tasks include: Use HTTPS to set up a connection between your website and Worldpay. Create the valid XML files that are used to communicate with Worldpay. Test your integration. 3.1 Use HTTPS to Connect HTTPS adds the security capabilities of the Secure Sockets Layer (SSL) encryption protocol to standard HTTP communications. To submit XML messages safely and securely to Worldpay s payment service, you must use HTTPS to set up a connection between your website and Worldpay. For important, high level technical guidance about your IP communications with us, and much more, see our Best Practice Guide at To use HTTPS to set up your connection: 1. You must register your domain with an SSL certificates provider. 2. Use a valid XML login and password to submit XML messages. Worldpay sent you your XML username and password when you opened your account. If you can t find them, contact Worldpay support to get them resent. To manage your credentials: a. Go to Merchant Interface > Profile > Merchant Environment. The Edit XML Password page appears. b. Select Enable XML API Users. c. To edit your XML password, click the yellow pencil icon [ ] next to XML Password.

15 XML Redirect Integration Guide > 3 Integrating with Worldpay 15 The number of dots displayed in the XML Password field does not relate to the number of characters in your password. d. In Password, enter your new password. Your new password must use at least 20 characters, including one number in the first 8 characters. Do not use ; or : symbols. e. In Password (again), re-enter your new password. f. Click Save XML Password. 3. Create valid XML messages that you can use to submit orders, order modifications and status inquiries to Worldpay (see Creating and submitting valid XML messages on the next page). 4. Set up your platform for submitting XML messages to Worldpay s payment service. Example scripts for ASP, Java, Java Servlet and PHP based platforms are available from the Worldpay website > Support Centre at 5. Submit your XML messages: To the test environment at To the production (live) environment at Before you can submit XML messages, Worldpay has to activate the test and production environments (contact corporatesupport@worldpay.com). You should also check that: The HTTPS content type is text/xml. The content length is specified correctly. Not specifying the content length will not create errors, but specifying it incorrectly will. The Worldpay payment service only accepts incoming XML messages if the originating IP address is registered for the merchant. For more information about registering and managing multiple IP address ranges, see the Merchant Interface Guide > Profile > Submenu items > Merchant Environment Error Code 4 Security error When you try to connect to the Worldpay payment service for the first time, you may get an Error Code 4 Security Error. This error code usually means one of the following issues: Issue type XML login XML password Issue The merchant code (XML login) that you used to set up the connection and the merchant code referenced by the XML message do not match. The XML password that you set up in the Merchant Interface and the XML password provided by the XML message do not match.

16 XML Redirect Integration Guide > 3 Integrating with Worldpay 16 Issue type IP address Environment Issue The originating IP address for the XML message is not registered to you. You are submitting XML messages to an inactive environment. This is usually because you have activated the test environment, but you are trying to submit messages to the production environment. Table 3: Error Code 4 Security Error For the full list of error codes, see XML error codes on page Creating and submitting valid XML messages The XML orders you submit to the Worldpay payment service must: Use correct XML syntax and conform to the Worldpay Document Type Definition (DTD). Contain content that complies with your contract with Worldpay, and is not more than 4KB in size Worldpay DTD (Document Type Definition) The Worldpay DTD (Document Type Definition) provides all the XML elements that you require for communicating with the Worldpay payment service and 3rd party processors. It includes detailed comments on the use of elements, and the structure of valid XML messages. The DTD includes elements (not a definitive list) for: Payment orders and order modifications (for example, messages to cancel or refund an order). 3D Secure orders and order modifications. FuturePay payments (repeat payments, used for subscriptions and other regular payments). Payment status inquiries (for example, to check if an order has been Authorised, Captured or Settled). Communicating with alternative payment methods (the non-card based payment methods supported by Worldpay). The Worldpay DTD is available to view and reference from You can also download the DTD from the Worldpay website > Support Centre at For important, high level technical guidance using our DTD and creating valid XML see our Best Practice Guide at Valid XML All the XML messages you sent to the Worldpay payment service must be valid.

17 XML Redirect Integration Guide > 3 Integrating with Worldpay 17 Good XML Form Your XML is well-formed if: Every start tag [ <exampletag> ] has a matching end tag [ </exampletag> ]. Elements do not overlap. There is only one root element [ <paymentservice> ]. Attribute values are always presented within quotes [ exampleattribute value= 23 ]. Elements do not have two attributes with the same name. Comments and processing instructions do not appear inside tags. No unescaped [ < ] or [ & ] signs occur in the element or attribute s character data. Reference the DTD (Document Type Definition) A valid XML message always includes a reference to the DTD (in this case, the Worldpay DTD [ paymentservice_v1.dtd ], so that the message can be checked against the DTD automatically. For more information about the referencing the Worldpay DTD in your messages, see XML and DTD declarations on page 19. Use declared elements only Every element, attribute and entity in the XML that you send to the Worldpay payment service must be declared in the DTD (in this case, the Worldpay DTD). XML elements can be declared to contain the following: XML data types NMTOKEN PCDATA CDATA Description Name tokens Parsed character data Character data or constants Name tokens (NMTOKEN) An XML name token [ NMTOKEN ] consists of: Table 4: XML element declared Alphanumeric and/or ideographic characters. The punctuation marks [ _ ], [ - ], and [ : ]. No other characters are allowed. An XML name token cannot contain spaces. If an attribute is declared in the DTD to contain name tokens, the values of that attribute must be valid XML name tokens. For example: <! ELEMENT amount EMPTY> <!ATTLIST amount value NMTOKEN #REQUIRED currencycode NMTOKEN #REQUIRED exponent ( ) #REQUIRED debitcreditindicator ( debit credit ) credit > Code example 1: Valid XML name tokens

18 XML Redirect Integration Guide > 3 Integrating with Worldpay 18 PCDATA You cannot include the following special characters in a PCDATA (Parsed Character DATA) section in the XML message: [&], [<], [>] and [ ]. If you want to use these characters, then you must use the equivalent hexadecimal character code: Character & Hexidecimal character code & > > < < " CDATA Table 5: Hexadecimal character codes You can include any data / characters in a CDATA (Character DATA) section, provided that the data / characters: Comply with the specified encoding. Do not contain the following character set (which is used to express the end tag): ]]> You must enclose a CDATA section between the start tag and the end tag. For example: < [CDATA [This text has not been parsed and can still be used]]> Code example 2: CDATA section

19 XML Redirect Integration Guide > 4 Structure of an XML Redirect order 19 4 Structure of an XML Redirect order This chapter describes how to create a valid XML Redirect order. All XML messages sent to Worldpay s payment service must: Reference the Worldpay DTD (Document TypeDefinition) at Always use the correct XML syntax and conform to the DTD (be valid XML). The content of XML orders must comply with your contract with Worldpay, and not exceed 4Kb in size. For general guidance on the Worldpay DTD and creating valid XML messages, see Creating and submitting valid XML messages on page 16. For high level guidance, see our Best Practice Guide at XML and DTD declarations All valid, well-formed XML files used in the XML Redirect integration model begin with an XML declaration. They must also contain a document type declaration, containing the root element paymentservice and reference to the public Worldpay payment service DTD (paymentservice_v1.dtd). <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE paymentservice PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//en" " Code example 3: XML and DTD declaration 4.2 DTD version number and Merchant code The paymentservice root element has two required attributes: The version number of the Worldpay DTD (paymentservice_v1.4dtd). Your merchant code (which is always written in capitals). To find your merchant code, go to Merchant Interface > Profile > Identification. <paymentservice version="1.4" merchantcode="mymerchant"> <submit> [Order information goes here] </submit> </paymentservice> 4.3 The order element The order element is: Code example 4: DTD version and Merchant Code Found within the submit element. Used to describe the goods or services that the shopper is ordering. ordercode and installationid are attributes of the order element.

20 XML Redirect Integration Guide > 4 Structure of an XML Redirect order ordercode attribute The ordercode attribute: Is a required attribute. Must have a unique value. Can be up to 64 characters in length. Spaces, quotation marks and code brackets ( < and >) are not allowed. If your shopper s browser doesn t have cookies enabled, it is possible that another person can access the shopper s session ID. This is because the URL contains the session ID. We recommend that you ask your shoppers to enable cookies on their web browsers. Cookies minimise the opportunity to record a session ID and misuse it. An order with a previously used order code cannot be processed correctly. If you use a previously used order code, you will receive error messages (error code 5) and have problems with reporting. For more information about error codes, see XML error codes on page 58. You can use the ordercode attribute to contain a Cart ID if the Cart ID is unique. If the Cart ID is not unique, then you must use the ordercode attribute with a unique number added to the static Cart ID installationid attribute The installationid attribute contains the identification code for your payment page customisation configuration. This attribute is required if you use the Hosted Payment Pages description and amount The first two order child elements are description and amount: Child element description amount Description The description element is used to contain a simple, one-line description of the order (up to 255 characters long). The amount element has three attributes: value, which specifies the total amount the shopper is expected to pay. currencycode, which specifies the currency (ISO 4217 code). exponent, which specifies where the decimal point or comma should be placed in the value, counting from the right. Table 6: description and amount child elements For a list of currency codes and their respective exponents, see ISO currency codes on page 50. <order ordercode= T installationid="123456"> <description>20 red roses from the MyMerchant webshop.</description> <amount currencycode= GBP exponent= 2 value= 5000 /> </order>

21 XML Redirect Integration Guide > 4 Structure of an XML Redirect order 21 Example note: The content is highlighted in purple ordercontent child element Code example 5: Order element and child elements The third order child element is ordercontent. The ordercontent child element is used to contain the order content. You can deliver the content of the order in HTML format. When supplying HTML order content: You must place all HTML tags between the <body> and </body> tags of a valid HTML document. You cannot use scripting in the order content. Always place the order content in a CDATA section to avoid parsing problems: <ordercontent> <! [CDATA [Place HTML content here]] > </ordercontent> Example note: The content is highlighted in purple. Code example 6: ordercontent paymentmethodmask child element The fourth order child element is paymentmethodmask. The paymentmethodmask child element: Limits the available payment methods to be shown to the shopper. Must contain at least one include element (which defines a single specific payment method), for example: <include code="visa-ssl"/>, where VISA-SSL is the included payment method code. You must specify a separate include element for every payment method available for your account. Alternatively, you can include: All the available payment methods by using an include element with the payment method code ALL. Only online payment methods by using an include element with the payment method code ONLINE. You can use the optional exclude element to exclude a particular payment method from the list of payment methods, for example: <exclude code="amex-ssl"/> excludes the payment method AMEX-SSL (American Express). In the following example, all the available payment methods will be offered to the shopper except American Express: <paymentmethodmask> <include code="all"/> <exclude code="amex-ssl"/> </paymentmethodmask> Code example 7: paymentmethodmask > exclude element 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 (see Customising the payment method selection pages on page 32).

22 XML Redirect Integration Guide > 4 Structure of an XML Redirect order 22 The MasterPass payment method mask is MASTERPASS-SSL For a list of payment method codes, see Payment method codes on page Shopper child element The fifth order child element is shopper. The shopper child element is used to provide extra information about the shopper in the XML order (for example the shopper address). If applicable, Worldpay can use the value of shopper: For risk assessment purposes. To send an to the shopper when the payment is authorised or refused. <shopper> <shopper address>jshopper@myprovider.int</shopper address> </shopper> Example note: The content is highlighted in purple. Code example 8: shopper shippingaddress and billingaddress shippingaddress is the sixth order child element. billingaddress is the seventh order child element. You can use these optional elements to pre-populate the billing address fields on the Worldpay payment pages. For card payments, billingaddress takes priority over shippingaddress: You supply: shippingaddress only billngaddress only shippingaddress and billingaddress What happens? The shippingaddress information is used to pre-populate the billing address fields on the payment pages. The billingaddress information is used to pre-populate the billing address fields on the payment pages. The billingaddress information is used to pre-populate the billing address fields on the payment pages. Worldpay ignores the shippingaddress information. However, the shippingaddress can still be stored by Worldpay and used to make Risk Management and Risk Guardian checks. Can shoppers change address information? Table 7: billingaddress and shippingaddress 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). Your system recorded as the billing address for the order.

23 XML Redirect Integration Guide > 4 Structure of an XML Redirect order 23 Can I hide 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, corporatesupport@worldpay.com. 4.4 statementnarrative You can use the statementnarrative element to specify the text that is displayed on the shopper s statement. <statementnarrative>statement narrative text goes here</statementnarrative> Example note: The content is highlighted in purple. Code example 9: statementnarrative Support for the statementnarrative element is currently restricted to a limited number of payment methods and acquirers. To find out more, contact corporatesupport@worldpay.com.

24 XML Redirect Integration Guide > 4 Structure of an XML Redirect order Example XML Redirect order <?xml version="1.0" encoding="utf-8"?><!doctype paymentservice PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//en" " <paymentservice version="1.4" merchantcode="mymerchant"> <submit> <order ordercode="t " installationid="123456"> <description>20 English roses from MYMERCHANT Webshop</description> <amount value="2600" currencycode="gbp" exponent="2"/> <ordercontent> <![CDATA[<center><table> <tr><td class="one width190" align="left" valign="top"><span style=" font-family: Arial, Helvetica, sans-serif; font-size: 12pt; color: #002469;">Product:</span> </td><tr><td class="one" align="left" valign="top"><span style=" font-family: Arial, Helvetica, sans-serif; font-size: 12pt; color: #002469;"><strong>Product title</strong></span></td></tr> </table></center>]]> </ordercontent> <paymentmethodmask> <include code="all"/> <exclude code="amex-ssl"/> </paymentmethodmask> <shopper> <shopper address>jshopper@myprovider.int</shopper address> </shopper> <shippingaddress> <address> <firstname>john</firstname> <lastname>shopper</lastname> <address1>shopperstreet</address1> <address2>shopperaddress2</address2> <address3>shopperaddress3</address3> <postalcode>1234</postalcode> <city>shoppercity</city> <state>shopperregion</state> <countrycode>nl</countrycode> <telephonenumber> </telephonenumber> </address> </shippingaddress> <billingaddress> <address> <firstname>john</firstname> <lastname>shopper</lastname> <address1>shopperstreet</address1> <address2>shopperaddress2</address2> <address3>shopperaddress3</address3> <postalcode>1234</postalcode> <city>shoppercity</city> <state>shopperregion</state> <countrycode>nl</countrycode> <telephonenumber> </telephonenumber> </address> </billingaddress> </order> </submit> </paymentservice> Example notes: The content is highlighted in red. Code example 10: XML Redirect order

25 XML Redirect Integration Guide > 4 Structure of an XML Redirect order 25 merchantcode ordercode <description> <amount> The merchant is the MYMERCHANT webshop, with the merchant code MYMERCHANT. The order is for 20 English roses, with the order code T The total amount the shopper must pay is (GBP). <paymentmethodmask> The allowed payment methods (include) are all methods except (exclude) for American Express (AMEX-SSL). <shippingaddress> <billingaddress> <firstname> <lastname> The shippingaddress and billingaddress elements are always included in the code in this order. If you enter the billingaddress element followed by the shippingaddress element, the order fails. The name of the shopper is John Shopper. Before you submit XML messages to the Worldpay payment service, we strongly recommend that you validate the XML your system creates. XML that does not conform to the Worldpay DTD ( is not accepted. For more information about creating valid XML messages, see Creating and submitting valid XML messages on page 16. There are a number of tools you can use to check and validate XML. For example, see Important Information for MCC 6012 Merchants You must make this change if you have the merchant code 6012 (Financial institution manual and automated, securities broker or dealer, insurance sales, insurance premiums, insurance carrier) and process UK domestic payments. This change applies even if you have additional merchant codes assigned to you, as well as MCC FuturePay payments are also affected Information to Collect Merchants with an MCC 6012 code must collect the following information for each transaction: The Account Number/ Primary Account Number (PAN) of the Primary Recipient The PAN (a unique identifier) must belong to the primary recipient. The primary recipient is the person or entity who has the direct relationship with the financial institution and has agreed to its terms and conditions. The primary recipient may or may not be the person or entity that makes the payment. When you collect the account number or the PAN, you must format the field in the following way: Card to card payments (for example, use a card to pay off a card) Send the first six digits and the last four digits of the recipient s PAN with no spaces. For example FFFFFFLLLL Card to non-card payments (for example, pay off a loan) Send the first 10 characters of the recipient account number.

26 XML Redirect Integration Guide > 4 Structure of an XML Redirect order 26 This Account Number or Primary Account Number field must only contain letters or digits, or can be left empty. If the information is not available, leave this field empty. Last Name Don t use special characters in the Account number/pan Use letters only, do not use digits. Use standard English characters avoid punctuation marks like accents and circumflexes. Date of Birth (DOB) Use the format DD-MM-YYYY (day, month, year) Some merchants collect the month and year of birth only. If you do this, modify your system so that you collect the day of birth along with the month and year. If you cannot provide the day of birth, modify your system so it cannot pass the date of birth value to Worldpay as part of the MCC 6012 changes. Never pass an empty value in the tag, or send an incomplete date of birth field. This is because an incomplete or blank date of birth may cause an increase in rejected transactions. Postcode The date of birth must always be in the past use digits only. A valid UK postcode in the format: AA9A 9AA A9A 9AA A9 9AA A99 9AA AA9 9AA AA99 9AA There must always be a gap between the two groups of letters and numbers in a UK postcode. Send the above details to the Worldpay WPG system. See MCC 6012 Technical Information below. Once we receive these details, we send them to the card issuer to screen as part of the transaction process. Implement these changes as soon as possible; you may be fined if you don t implement the changes MCC 6012 Technical Information DTD (Document Type Definition) changes The paymentservice_v1 DTD contains elements specific to MCC 6012;this means you can pass the primary recipient s data to us at Worldpay. If you integrate with Worldpay using CG Redirect, and you are using MCC6012, you must always send us the additional data for primary recipients. This is because when the order is created, the payment method is unknown.

27 XML Redirect Integration Guide > 4 Structure of an XML Redirect order 27 The new elements are highlighted in purple: <!ELEMENT order (description, amount, risk?, ordercontent?, (paymentmethodmask paymentdetails payasorder ), shopper?, shippingaddress?, billingaddress?, branchspecificextension?, redirectpageattribute?, paymentmethodattribute*, echodata?, statementnarrative?, hcgadditionaldata?, thirdpartydata?, shopperadditionaldata?) > <!-- Used to collect merchant-held data required by Visa for MCC6012 merchants --> <!ELEMENT shopperadditionaldata (shopperaccountnumber?, lastname?, birthdate?, postalcode?) > <!ELEMENT shopperaccountnumber (#PCDATA)> Code example 11: MCC 6012 additional fields The lastname, birthdate and postalcode elements already exist in the DTD. All the new tags are optional Worldpay does not monitor whether an MCC6012 merchant passes the data or not. It is you (the merchant) who must ensure that you capture the data and send it to Worldpay. Format of the MCC 6012-specific fields Field shopperaccountnumber lastname Description This field can be empty. It contains a maximum of 10 characters. It must contain only letters or digits. This shopper account number represents the unique account identifier of the primary recipient. This can be a partial PAN (Primary Account Number) number: so you must send the first 6 digits + last 4 digits, for example FFFFFFLLLL. You can also send up to 10 characters from the account number. If the content of this field does not follow these rules, you receive this error message: The shopperaccountnumber cannot be longer than 10 characters or The shopperaccountnumber must contain only digits or letters. This field can be empty.

28 XML Redirect Integration Guide > 4 Structure of an XML Redirect order 28 Field birthdate postalcode Description It must not contain digits. If the content of the lastname does not follow the rules above, you receive this error message: Digits are not allowed in lastname tag. This must be a valid date in the past. It is best to supply the day, month and year in the format DD-MM-YYYY. If you are unable to supply the day value in the date of birth, then do not send the D.O.B (date of birth). A blank or partially supplied date of birth may cause an increase in declined transactions. If the content of the birthdate is not correct, you receive an error message. This field can be empty. It must be a valid UK postal code (one of the format: AA9A 9AA, A9A 9AA, A9 9AA, A99 9AA, AA9 9AA, AA99 9AA). A valid postcode always has a blank space between the two groups of letters and numbers. If the content of the postal code is not correct, you receive this error message: The postalcode must contain a valid UK postal code. Table 8: Format of the MCC 6012-specific fields

29 XML Redirect Integration Guide > 4 Structure of an XML Redirect order 29 Example of the correct XML code <?xml version="1.0" encoding="utf-8"?><!doctype paymentservice PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//en" " <paymentservice version="1.4" merchantcode="demo"> <submit> <order ordercode="jsxml "> <description>&nbsp;</description> <amount value="100" currencycode="eur" exponent="2"/> <ordercontent> </ordercontent> <paymentmethodmask> <include code="all"/> </paymentmethodmask> <shopper> <shopper address>sp@worldpay.com</shopper address> </shopper> <shippingaddress> <address> <firstname>john</firstname> <lastname>doe</lastname> <street>the Science Park</street> <housenumber>270</housenumber> <postalcode>cb4 0WE</postalCode> <city>cambridge</city> <countrycode>gb</countrycode> </address> </shippingaddress> <shopperadditionaldata> <shopperaccountnumber>1234abc</shopperaccountnumber> <lastname>oana</lastname> <birthdate> <date dayofmonth="10" month="10" year="2000"/> </birthdate> <postalcode>cb4 0WE</postalCode> </shopperadditionaldata> </order> </submit> </paymentservice> Code example 12: An example of the additional fields for MCC 6012 merchants FuturePay Payments and Regular Payment Agreements The MCC 6012 requirements described in section Important Information for MCC 6012 Merchants on page 25 also apply to FuturePay payments. If you, the merchant, have an MCC6012 classification you should always send the parameters when you create a Future pay payment or a regular payment agreement. This is because with an HTML Visible Integration, the payment method is unknown at the moment you submit the request to Worldpay. As the payment method is unknown, shoppers may select VISA as the payment method. If this happens, your system sends the additional parameters to VISA and there will be no problem. If shoppers select a different non-visa payment method, then there is no problem in any case. If you need to update the primary recipient information once a FuturePay agreement has been set up then you should use the FuturePay update functionality and provide the new data in the appropriate field. This will work with existing FuturePay orders. Where Primary Recipient data has been previously provided this will update the existing data, where none has previously provided this will append this to the existing agreement.

30 XML Redirect Integration Guide > 4 Structure of an XML Redirect order 30 If you want to remove associated primary recipient data from a transaction then you should pass the relevant tag with no value. To remove a previously saved date of birth submit the date of birth tag populated with 0 : <birthdate> <date dayofmonth="0" month="0" year="0"/> </birthdate> Example of a Primary Recipient Update message: Code example 13: D.O.B tag populated with zero <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE paymentservice PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//en" " <paymentservice version="1.4" merchantcode="upgrade"> <modify> <futurepayagreementmodification agreementid=""> <shopperadditionaldata> <shopperaccountnumber>asd123</shopperaccountnumber> <lastname>test</lastname> <birthdate> <date dayofmonth="02" month="09" year="1983"/> </birthdate> <postalcode>cb4 0WE</postalCode> </shopperadditionaldata> </futurepayagreementmodification> </modify> </paymentservice> Code example 14: Primary Recipient Update message If you don t supply the correct data, error messages appear to the shopper. This might confuse the shopper as the errors are not related to data s/he submits. Most shoppers will not know that the error messages are due to data sent by you, the merchant.

31 XML Redirect Integration Guide > 5 Redirecting to the payment pages 31 5 Redirecting to the payment pages In this chapter, we look at how to redirect your shoppers to Worldpay s payment pages, and how to customise the payment method selection pages. To parse XML responses from the Worldpay payment service, you are strongly advised to use an industry standard XML parser. For more information about XML parsers, see Redirecting the shopper When the Worldpay payment service has received a valid order, it will send an XML response to your system. The response includes the URL to redirect the shopper to the Worldpay payment pages and has to be parsed by your system. An example XML response is shown below. <?xml version="1.0"?> <!DOCTYPE paymentservice PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//en" " <paymentservice merchantcode="mymerchant" version="1.4"> <reply> <orderstatus ordercode="t "> <reference id=" "> MYMERCHANT^T </reference> </orderstatus> </reply> </paymentservice> Example notes: The content is highlighted in red. Code example 15: XML response <reply> ordercode <reference> The redirect information is contained in the reply element. The order code to match the response to the order in your back-office system. The redirect URL is contained in the reference element. This URL must be used exactly as-is when redirecting the shopper. If the shopper was redirected in the test environment, the example redirect URL would be: orderkey=mymerchant^t Reference id attribute The id attribute of the reference element 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 or Accept Giro. In the case of Accept Giro, the reference id number should be printed on the Accept Giros as the payment reference.

32 XML Redirect Integration Guide > 5 Redirecting to the payment pages 32 If you are sending the order solely to acquire this reference id, there is 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 V.me by Visa and MasterPass payments The XML response shows the type of card used in the transaction (for example, a Visa credit card), but cannot show if the V.me by Visa digital wallet or MasterPass was used or not. If you want to identify whether a transaction was made with V.me by Visa you can: View the payment details in the Merchant Interface. Add the Digital Wallet column to the Get Statement report. Request the addition of the Transaction Download report through your relationship manager Performing the redirection How the actual redirection is performed depends on the implementation of your system. Orders received by Worldpay s payment service are available for a maximum period of five days. The shopper must be redirected to submit their payment details during this period. Worldpay payment pages do not support iframes. 5.2 Customising the payment method selection pages Appending the Redirect URL The redirect URL provided in the response from our payment service is sufficient to redirect the shopper to the payment pages. However, you can add additional parameters to the redirect URL to: Customise the appearance of the payment method selection pages. Provide result URLs to inform the shopper of the result of their payment attempt. All appended parameters and their values must be URL-encoded to ensure correct processing. Many platforms have tools (built-in functions) that can automatically URL-encode information. For programming examples see: The PHP function list at The Microsoft Developer Network at The attributes described in the sections below can be used with redirect URLs. Worldpay does not take responsibility for the operation or content of an external link.

33 XML Redirect Integration Guide > 5 Redirecting to the payment pages country and language attributes The optional country and language attributes set the default country and the language of the payment method selection pages: Attribute Permitted values Example country Two-letter ISO 3166 country code &country=gb language Two-letter ISO language code &language=en Table 9: country and language attributes The language attribute applies to the text originating from the Worldpay payments service, not to the order description and order content you supplied. The country attribute influences which of the available payment methods are presented to the shopper. For example, if you set the country as the Netherlands the shopper would be presented with a range of international credit cards and Netherlands-specific payment methods. You can also specify the country and the language independently from each other. For example, you could present the payment methods for the Netherlands in Swedish. The shopper has the option to select a different language and country on the first payment method selection page. The default position of the language and country selection fields is at the bottom of the payment method selection page. The position of these fields can be changed by Worldpay on request. You can switch the language and country selection off in the Merchant Interface > Profile page. It is switched on or off for all transactions, it cannot be done on a per transaction basis. For more information, see the Merchant Interface Guide. For definitive information about country and language codes, see You can also find out more about country codes in ISO country codes on page bodyattr The optional bodyattr attribute sets the body attributes of the page. All body attributes that are valid in the <BODY> tag in HTML documents are permitted. &bodyattr=bgcolor%3d%22black%22 Example notes: The content is highlighted in purple. Code example 16: bodyattr In this example the background colour has been set to black (for more body attributes, see external HTML documentation). The value of the attribute is URL-encoded. Background image You can use the bodyattr attribute to define a background image for the payment method selection pages. If you use a background image the host of the URL of the image must have the same IP address as the order. The payment method selection pages run in a secure environment.

34 XML Redirect Integration Guide > 5 Redirecting to the payment pages 34 Use the Worldpay HTTPS proxy if the image is in a non-secure environment. This is achieved by putting the following string in front of the URL of the image: Code example 17: HTTPS proxy string fontattr The fontattr attribute sets the font attributes of the payment method selection screen. &fontattr=face%3d%22arial%22+color%3d%22white%22 Example notes: The content is highlighted in purple. Code example 18: fontattr In this example, the font face is set to Arial and the font colour set to white. When the font indicated is not available on the shopper's system, the browser's default font is used. It is possible to define alternative fonts by separating them with a comma (for example, Arial, Verdana, Helvetica) Result URLs The result URLs must reside on your server and are used to: Provide feedback about the payment to the shopper. Report the payment status to your system. Attribute Description Example successurl Sets the success URL &successurl=http%3a%2f%2fwww.webshops.int%2fsuccess.asp pendingurl Sets the pending URL &pendingurl=http%3a%2f%2fwww.webshops.int%2fpending.php failureurl Sets the failure URL &failureurl=http%3a%2f%2fwww.webshops.int%2ffailure.php cancelurl Sets the cancel URL &cancelurl=http%3a%2f%2fwww.webshops.int%2fcancel.php Table 10: Result URLs You can append request variables and values to the result URLs (which must also be URLencoded). For more information about the result URLs see Reporting results to the shopper on page preferredpaymentmethod The optional preferredpaymentmethod attribute sets the preferred payment method. This gives you the ability to pre-select the payment method for the shopper. &preferredpaymentmethod=visa-ssl Example notes: The content is highlighted in purple. Code example 19: preferredpaymentmethod

35 XML Redirect Integration Guide > 5 Redirecting to the payment pages 35 In this example, the payment method is VISA (VISA-SSL). You may want to set a preferred payment method if: You only want to accept one specific payment method (for this particular transaction). You want to bypass the payment methods presented by Worldpay, because the shopper has already chosen a preferred payment method in the shopping application on your server. If you specify a preferred payment method, the shopper will not have the option to select a language and country on the first payment method selection page. Setting V.me by Visa or MasterPass as the preferred payment methods You can also set V.me by Visa and MasterPass as the preferred payment method: &preferredpaymentmethod=vme-ssl Example notes: The content is highlighted in purple. Code example 20: V.me by Visa preferred payment method In this example, the payment method is V.me by VISA (VME-SSL). It could have been MasterPass by substituting MASTERPASS-SSL for VME-SSL. The country code must belong to a valid V.me by Visa country, otherwise the payment method cannot be displayed and an error will be returned. For more information, see Redirect URL: full example 0&country=GB&language=en&successURL=http%3A%2F%2Fwww.webshops.int.com%2Fsuccess.asp&failure URL=http%3A%2F%2Fwww.webshops.int%2Ffailure.php&pendingURL=http%3A%2F%2Fwww.webshops.int%2F pending.html&cancelurl=http%3a%2f%2fwww.webshops.int%2fcancel.html&preferredpaymentmethod=v ISA-SSL Code example 21: Redirect URL: full example For more information about customising the look and feel of the Worldpay payment pages, see the Customising (Advanced) Guide.

36 XML Redirect Integration Guide > 6 Reporting results to the shopper 36 6 Reporting results to the shopper This chapter describes how the shopper is informed about the result of their payment. There are two options: Online, through redirection to a result URL. Through an notification. For an overview of the XML Redirect payment process, see XML Redirect model on page Result URL When the shopper has selected an online payment method (such as a credit card) and has entered their payment details: 1. The payment information is submitted to the Worldpay payment service. 2. Worldpay sends the payment information to the financial institutions (acquirers) for authorisation. 3. The result of the authorisation request (payment status) is reported to Worldpay online. The payment status can be either AUTHORISED or REFUSED. If a shopper terminates the payment process before submitting their payment details, the order can stay in the Worldpay system without a payment status. 4. To inform the shopper about the result of the payment, Worldpay redirects the shopper's browser to a corresponding results URL on your system Offline payment methods If the shopper selects an offline payment method (such as a bank transfer), the result of their submitted payment will not be known immediately. Instead of being redirected to a results URL, the shopper is redirected to the pendingurl on your system that informs them that: The order has been placed. You will wait for the payment before shipping the merchandise. For more information about the payment statuses of offline payments, see the Payment Status Definitions Guide.

37 XML Redirect Integration Guide > 6 Reporting results to the shopper Payment results Payment result AUTHORISED PENDING REFUSED CANCELLED Description / Comments The Worldpay payment service redirects the shopper to the successurl on your system where the successful authorisation of the payment is reported. Offline payment methods: The Worldpay payments service redirects the shopper to the pendingurl on your system with information that the order has been placed but that the payment result is not yet available (applies to off-line payment methods). Alternative payment methods: The Worldpay payments services redirects the shopper to your pendingurl, where you can view additional information about the transaction status. For more information, see the Payment Status Definitions Guide The Worldpay payments service redirects the shopper to the failureurl on your system informs where the refused transaction is reported. The Worldpay payments service redirects the shopper to the cancelurl on your system informs where the cancelled transaction is reported. Table 11: Payment results Example redirect URL The following example shows a redirect URL that redirects the shopper to your success page. &paymentstatus=authorised&paymentamount=2600&paymentcurrency=eur &mac=0083c47880f0533d773c350ee0d51cfc Code example 22: Example redirect URL Worldpay appends a number of parameters to the URL. Any request variable that you appended to the result URLs is unaltered and will also be part of the above redirect message. For more information, see Appending the Redirect URL on page 32. When a shopper cancels a payment, the redirect URL will not contain the parameter paymentstatus. 6.2 Transaction status in the pendingurl For alternative payments, the transaction status in the pendingurl: Indicates the overall status of a transaction. Shows the reason why a shopper has been redirected to your pendingurl. For example, the shopper can be redirected to a pendingurl of the following form: OR Code example 23: pendingurl

38 XML Redirect Integration Guide > 6 Reporting results to the shopper 38 You can use the transaction status information to manage the pending scenario appropriately, for example by allowing the shopper to retry or select another payment type if an ERROR, FAILURE, or EXPIRED status is returned. The various transaction statuses reported by the payment method provider in the pendingurl are described in the following table. Transaction status OPEN ERROR FAILURE EXPIRED Description / Comments The transaction is awaiting action by the shopper. This is the result for any offline payment method. There was a technical problem during the transaction. Some payment method providers also return this response when a shopper has cancelled their transaction. The payment has been refused. This is an uncommon response because most alternative payment methods involve pre-funding rather than real-time authorisations. Additionally, transactions are cancelled by the shopper rather than declined by a real-time authorisation. The shopper session has expired. This status is returned if the shopper initiates a transaction, but does not complete it. 6.3 HTTPS proxy Table 12: Transaction statuses in the pendingurl If a shopper is redirected from the secure location on the Worldpay payment service to a non-secure location on your system, the browser will usually display a security warning that may confuse the shopper. To avoid this warning our payment service provides an HTTPS proxy showing the result URL through the existing secure connection, instead of redirecting the shopper directly. This feature is activated by default but can be switched off in the Merchant Interface > Profile page. If you already have a secure environment in place the HTTPS proxy is not required HTTPS proxy restrictions The HTTPS proxy has the following restrictions: For security reasons, the feature will only work directly after a payment has been processed. This means that you must take a payment through the entire payment cycle to test the proxy functionality. The result pages must reside on the same machine (IP address) that sends the orders to the Worldpay payment service. Pages that redirect through the 302 HTTP return code do not function in combination with the proxy. Result pages containing a redirection If you want to implement a redirection within the result page that is compatible with the HTTPS proxy, then Worldpay recommends using a HTTP-refresh within the meta tag of the document. For example:

39 XML Redirect Integration Guide > 6 Reporting results to the shopper 39 <meta http-equiv="refresh" content="0; url=somewhere.asp">. Code example 24: HTTP-refresh within meta tag You can use the following non-w3 supported redirection method within the result URL in combination with the Worldpay proxy: <html> <head> <script language="javascript"> <!-- self.location='/redirectfolder/thankyou.asp/; //--> </script> </head> </html> Code example 25: Redirection method used with HTTPS proxy This method is supported but only if implemented in the way shown above. You should replace the redirection URL with the desired URL. 6.4 Notifying the shopper by As well as showing the shopper the status of their payment through the result pages, you can also send the shopper an with payment status information. The can be sent by either your system or the Worldpay payment service. In both cases, the shopper s address must be made available to the system. If the is sent: By your system, then the is sent after you receive either a signed redirect message or an automated order notification from Worldpay. You can choose when to send the and what information to provide to the shopper. By the Worldpay system, then your account is configured so that Worldpay sends an to the shopper after a successful authorisation or a refusal. You can change the settings and text of the s in the Merchant Interface > Edit Channels page. For more information, see the Merchant Interface Guide.

40 XML Redirect Integration Guide > 7 Securing the payment status 40 7 Securing the payment status This chapter tells you about Worldpay s redirect message to the result URL. Worldpay's redirect message to the result URL contains a number of parameters that include: paymentstatus 7.1 About the MAC A digital signature, called the Message Authentication Code (MAC) The MAC provides a digital signature that allows you to verify that the redirect message: Originated from Worldpay. Has not been modified since Worldpay signed it. After successfully verifying the redirect message you can reliably use its information to update the order's payment status on your system. This method applies to the payment statuses AUTHORISED and REFUSED. It is possible to ignore the MAC, or even have this feature switched off. When switched off the redirect message contains fewer parameters. Worldpay recommends that you use other payment status reporting tools (for example, order notifications), to update the order's payment status on your system. For more information, see the Order Notifications Guide. 7.2 Creating and adding the MAC The Message Authentication Code (MAC) is created using a key-dependent one-way hash function. To secure the signature: 1. A secret value (password), known only to you and Worldpay, is added to the redirect parameters before the hash value is calculated. 2. The hash value is then added to the redirect message when it is sent, but the secret value is not. &paymentstatus=authorised&paymentamount=1400&paymentcurrency=gbp &mac=25eefe952a6bbd09fe1c2c09bca4fa09 Example notes: Code example 26: signed redirect message (MAC) In this example of a signed redirect message, the signature (MAC, highlighted in purple) is added to the message as a hexadecimal representation of the hash value Receiving the signed redirect message When you receive the signed redirect message, you can calculate the hash value in exactly the same way, by: Adding the secret value to the parameters of the message. Applying the hash function to the message.

41 XML Redirect Integration Guide > 7 Securing the payment status 41 The calculated hash value should exactly match the hash value that Worldpay has added to the redirect message. When Worldpay redirects the shopper from the payment pages to the result URLs, the definition of orderkey that is used (orderkey=admincode^merchantcode^ordercode) is different from that used for redirecting the shopper to the Payment Method Selection pages (orderkey=merchantcode^ordercode) (see Customising the payment method selection pages on page 32) Calculating the MAC The MAC is calculated over the sensitive data in the redirect message (not the entire redirect message). To calculate the MAC, the values of the following parameters and in the following order are concatenated: orderkey+paymentamount+paymentcurrency+paymentstatus+[mac secret] Example notes: Code example 27: Concatenating parameters to calculate the MAC orderkey [mac secret] The orderkey parameter displayed in the redirect message is not necessarily the same as the orderkey as specified in the reference element of the Worldpay XML response to an order. The last value is the MAC secret (password) known only to you (the merchant) and Worldpay. An actual redirect message can contain more variables than shown in the example, but only the above mentioned variables are included in the calculation of the MAC. After concatenation After concatenation, the message is fed into a MD5 hashing function, which returns a 128-bit value. The hexadecimal representation of this value must be compared with the value of the MAC provided by Worldpay in the signed redirect message. Worldpay always uses lower-case hex characters. Most development environments offer MD5 as a standard algorithm. If not, a library should be available to offer an MD5 implementation. To verify a redirect message, concatenate the variables, where the MAC secret MYADMINCODE^MYMERCHANT^T GBPAUTHORISED@p-p1epie The hex representation of the resulting hash value is: 62441c9c7dce375a6913e55f34fc6d1a Code example 28: Concatenating parameters to calculate the MAC Code example 29: Hex representation of the hash value This calculated MAC equals the value provided in the signed redirect message. This guarantees that the message corresponds to order code T with a successfully authorised payment for (GBP)

42 XML Redirect Integration Guide > 7 Securing the payment status Setting the MAC secret The MAC secret (password) is set in the Merchant Interface > Profile page. The MAC secret must be a combination of English alphanumeric characters and symbols, between 20 and 30 characters long. It must have all of the following: An upper case letter A lower case letter A number A symbol which can be any of the following: #, $, %, ^, &, *, (, ), _, +, -, =, `, \\, ], [, \, ;, /,.,,,, }, {, ", :,?, >, < } If you are a new merchant, the MAC feature is enabled with a system-generated password. You are only required to enter a new password and save the profile to be able to check the MAC in the redirect message. The redirection of the shopper to your result URL is not affected if the MAC feature is enabled without the MAC being checked. You can also disable the MAC feature in the Merchant Interface. However, this will cause the previously set password to be lost. If you disable the MAC then there is a risk that the parameters within the redirect message could be intercepted and modified.

43 XML Redirect Integration Guide > 8 Testing in the XML Redirect model 43 8 Testing in the XML Redirect model This chapter provides guidance on testing. In this chapter, we will look at: Your connection with the Worldpay payment service. XML Redirect orders, including 3D Secure orders. 8.1 Test environment The URL for the Worldpay test environment is: Before submitting XML messages to the test environment, check that: The HTTPS content type is text/xml. The content length is specified correctly. You will not create errors if you do not specify the content length, but you will create errors if you specify the length incorrectly. Before you can submit XML messages, the test environment must be activated for your account by Worldpay. For more information, contact corporatesupport@worldpay.com The Worldpay payment service only accepts incoming XML messages if the originating IP address is registered to you. For more information about registering and managing multiple IP address ranges, see the Merchant Interface Guide Differences between the test and production environments There are some important differences between the test environment and the production environment. These differences are particularly important if you are testing 3D Secure orders. Element issuerurl paresponse Comments The issuerurl element in the test environment contains no parameters: However, in the production environment this URL would normally have parameters in place. For example: The PaReq, TermUrl and MD elements must be posted with these parameters. The redirect to the issuerurl must always be made with a POST and not a GET. The acceptable values for paresponse in the test environment (IDENTIFIED or NOT_ IDENTIFIED) are significantly shorter than the values returned from the issuer in production, where the typical length can be up to 4.7 KB. The paresponse values:

44 XML Redirect Integration Guide > 8 Testing in the XML Redirect model 44 Element PaReq Comments Must be collected by your system for sending to Worldpay in the second order message. Require extra storage space. Note: Do not submit a long (4.7KB) paresponse to the test environment, as this causes a parsing error. The value of the PaReq attribute must be URL encoded before transmission to the issuer. 8.2 Test values Table 13: 3D Secure: testing and production environments You can simulate different outcomes when submitting XML Redirect orders by entering the following values as the cardholder name (<cardholdername>): Value REFUSED REFERRED ERROR Description Simulates a REFUSED payment. Simulates a refusal with the refusal reason REFERRED. Simulates a payment that ends in an ERROR. Table 14: Test values 8.3 Test credit and debit card numbers To help you test your system, Worldpay provides a set of test credit and debit card numbers. For the list of test credit and debit card numbers, see Test card numbers on page Testing captures and refunds You can simulate captures and refunds: In the Merchant Interface > Payment and Order Details by using the Capture or Refund button. In the test environment by sending an XML capture or refund order modification. 8.5 Testing 3D Secure orders To help you test 3D Secure orders, Worldpay provides a dummy card issuer site. The value of the cardholdername element in the XML order message can be used to simulate various outcomes, as shown in Testing 3D Secure orders above. Before you can test 3D Secure orders your Worldpay account must be enabled for 3D Secure. To enable 3D Secure, contact corporatesupport@worldpay.com.

45 XML Redirect Integration Guide > 8 Testing in the XML Redirect model 45 cardholdername value 3D NO3D 3DVEERROR Any other value Test environment behaviour The payment card is participating in 3D Secure. The simulator authentication page is initiated, where you can select further options. The payment card is not participating in 3D Secure. The simulator authentication page is not initiated. The 3D Secure result is Authentication Offered but not Used. The payment card is participating, but simulates a system/connectivity issue that occurs before the cardholder is asked to authenticate. The simulator authentication page is not initiated. The 3D Secure result is Authentication Unavailable. Any other value initiates a normal, non-3d Secure transaction process. Payer authentication outcomes Table 15: 3D Secure testing: cardholdername value You can use the value of the paresponse element to manipulate the outcome of the payer authentication. Using the dummy issuer site, the following options can be selected from the drop-down menu: Option IDENTIFIED NOT_ IDENTIFIED UNKNOWN_ IDENTITY ERROR Outcome(s) A value of: A value of: IDENTIFIED means that the shopper s identity has been successfully verified. IDENTIFIED with No XID also means that the shopper s identity has been successfully identified. NOT_IDENTIFIED means that the shopper s identity could not be verified. NOT_IDENTIFIED with No XID also means that the shopper s identity could not be verified. A value of UNKNOWN_IDENTITY means that authentication failed. A value of ERROR (or any other value than those described above) means that the verification process itself failed. Table 16: Payer authentication outcomes

46 XML Redirect Integration Guide > Appendix A: Payment method codes 46 Appendix A: Payment method codes To determine which payment methods the shopper can use, you can use either: The paymentmethodmask variable. The preferredpaymentmethod variable. The payment method codes are shown in the tables below. For the full list of payment methods, see the Worldpay DTD at For more information about supported alternative payment methods, see the Alternative Payment Methods Guide. Credit and debit cards Payment method Payment method code Area Comments AirPlus AIRPLUS-SSL International - American Express SSL AMEX-SSL International - Aurore AURORE-SSL International - Carte Bancaire CB-SSL France - Carte Bleue CARTEBLEUE-SSL France - Dankort DANKORT-SSL Denmark - Diners DINERS-SSL International - Discover Card DISCOVER-SSL United States - GE Capital GECAPITAL-SSL International - Japanese Credit Bank JCB-SSL International - Laser Card LASER-SSL Ireland - Maestro MAESTRO-SSL International - MasterCard ECMC-SSL International The name Eurocard is no longer in use. MasterPass MASTERPASS-SSL International - PayPal PAYPAL-EXPRESS International Card/eWallet UATP UATP-SSL International - V.Me VME-SSL International - Visa VISA-SSL International Visa Credit/Debit/Electron Table 17: Credit and debit cards

47 XML Redirect Integration Guide > Appendix A: Payment method codes 47 Online debit methods Payment method Payment method code Area Comments Electronisches Lastchriftverhfahren Maestro ELV-SSL Germany As a result of SEPA regulations, there are some changes you need to make to your XML submissions for ELV payments. For more information, see the SEPA Integration guide. MAESTRO- SSL UK Depending upon the issuer policy, you may need to include either the issuer number or the start date in the paymentdetails. Table 18: Online debit methods Offline payment methods Payment method Direct bank transfer Redirect bank transfer Payment method code TRANSFER_ AT-BANK TRANSFER_ BE-BANK TRANSFER_ DK-BANK TRANSFER_FI- BANK TRANSFER_ FR-BANK TRANSFER_ DE-BANK TRANSFER_ GR-BANK TRANSFER_IT- BANK TRANSFER_ JP-BANK TRANSFER_ LU-BANK Area Comments Austria - Belgium Denmark Finland France Germany Greece Italy Japan Luxembourg

48 XML Redirect Integration Guide > Appendix A: Payment method codes 48 Payment method Payment method code TRANSFER_ NL-BANK TRANSFER_ NO-BANK TRANSFER_ PL-BANK TRANSFER_ ES-BANK TRANSFER_ SE-BANK TRANSFER_ CH-BANK TRANSFER_ GB-BANK Area Netherlands Norway Poland Spain Sweden Switzerland UK Giropay GIROPAY-SSL Germany - Signed Direct Debit Unsigned Direct Debit PERMANENT_ SIGNED_DD SINGLE_ UNSIGNED_ DD Germany, Netherlands, Spain and USA Germany, Netherlands, Spain and USA Comments - As a result of SEPA regulations, there are some changes you need to make to your XML submissions for Unsigned Direct Debits in The Netherlands. For more information, see the SEPA Integration guide. Table 19: Offline payment methods Online Alternative Payment Methods (APMs) Payment method China Union Pay Payment method code CHINAUNIONPAY- SSL Area International - Comments ENETS ENETS-SSL Singapore Bank transfer Swedbank HANSABANK-SSL Sweden Bank transfer IDEAL IDEAL-SSL Netherlands Bank transfer As a result of SEPA regulations, there are some changes

49 XML Redirect Integration Guide > Appendix A: Payment method codes 49 Payment method Payment method code Area Comments you need to make to your XML submissions for Authenticated Dutch Direct Debits that are initiated with an IDEAL payment. For more information, see the SEPA Integration guide. Table 20: Online Alternative Payment Methods (APMs)

50 XML Redirect Integration Guide > Appendix B: ISO currency codes 50 Appendix B: ISO currency codes The currencies accepted by the Worldpay payment service are listed in the table below. For the full ISO 4217 list of ISO currency codes, see Worldpay does not take responsibility for an external link s operation or content. The values in the orders sent to Worldpay use exponent instead of decimal delimiters. The currency code is always presented in capitals. For more information, see ISO currency codes Currency ISO currency code Exponent Nuevo Argentine Peso ARS 2 Australian Dollar AUD 2 Brazilian Real BRL 2 Canadian Dollar CAD 2 Swiss Franc CHF 2 Chilean Peso CLP 0 Yuan Renmimbi CNY 2 Colombian Peso COP 2 Czech Koruna CZK 2 Danish Krone DKK 2 Euro EUR 2 Pound Sterling GBP 2 Hong Kong Dollar HKD 2 Hungarian Forint HUF 2 Indonesian Rupiah IDR 2 Iceland Krona ISK 0 Japanese Yen JPY 0 Kenyan Shilling KES 2 South Korean Won KRW 0 Mexican Peso MXP 2 Malaysian Ringgit MYR 2

51 XML Redirect Integration Guide > Appendix B: ISO currency codes 51 Currency ISO currency code Exponent Norwegian Krone NOK 2 New Zealand Dollar NZD 2 Philippine Peso PHP 2 New Polish Zloty PLN 2 Swedish Krone SEK 2 Singapore Dollar SGD 2 Thai Baht THB 2 New Taiwan Dollar TWD 2 US Dollar USD 2 Vietnamese New Dong VND 0 South African Rand ZAR 2 Table 21: ISO currency codes

52 XML Redirect Integration Guide > Appendix C: ISO country codes 52 Appendix C: ISO country codes The countrycode element is used in XML messages. The country code is an upper-case two letter ISO 3166 standard country code, as shown in the following example: <address> <countrycode>gb</countrycode> </address> Code example 30: countrycode For the full ISO 4217 list of ISO country codes, see Worldpay does not take responsibility for an external link s operation or content.

53 XML Redirect Integration Guide > Appendix D: Acquirer response codes 53 Appendix D: Acquirer response codes Worldpay uses ISO 8583 response codes in orderstatusevent messages to show you the status of a payment (for example, AUTHORISED or REFUSED). The response codes (including their numeric value and their mapping to a status) are listed in the table below. For more information about the different payment statuses that a payment can obtain during its life cycle, see the Payment Status Definitions Guide. ISO 8583 response codes Card message value Status Code message value Statue 0 AUTHORISED AUTHORISED 85 REJECTED BY CARD ISSUER REFUSED 2 REFERRED REFUSED 91 CREDITCARD ISSUER TEMPORARILY NOT REACHABLE REFUSED 4 HOLD CARD REFUSED 97 SECURITY BREACH REFUSED 5 REFUSED REFUSED 3 INVALID ACCEPTOR ERROR 8 APPROVE AFTER IDENTIFICATION REFUSED 12 INVALID TRANSACTION ERROR 13 INVALID AMOUNT REFUSED 14 INVALID ACCOUNT ERROR 15 INVALID CARD ISSUER REFUSED 19 REPEAT OF LAST TRANSACTION ERROR 17 ANNULATION BY CLIENT REFUSED 20 ACQUIRER ERROR ERROR 28 ACCESS DENIED REFUSED 21 REVERSAL NOT PROCESSED, MISSING AUTHORISATION ERROR 29 IMPOSSIBLE REFERENCE NUMBER REFUSED 24 UPDATE OF FILE IMPOSSIBLE ERROR 33 CARD EXPIRED REFUSED 25 REFERENCE NUMBER CANNOT BE FOUND ERROR 34 FRAUD SUSPICION REFUSED 26 DUPLICATE REFERENCE NUMBER ERROR 38 SECURITY CODE EXPIRED REFUSED 27 ERROR IN REFERENCE NUMBER FIELD ERROR 41 LOST CARD REFUSED 30 FORMAT ERROR ERROR 43 STOLEN CARD, PICK UP REFUSED 31 UNKNOWN ACQUIRER ACCOUNT CODE ERROR 51 LIMIT EXCEEDED REFUSED 40 REQUESTED FUNCTION NOT SUPPORTED ERROR 55 INVALID SECURITY CODE REFUSED 58 TRANSACTION NOT PERMITTED ERROR 56 UNKNOWN CARD REFUSED 64 AMOUNT HIGHER THAN PREVIOUS TRANSACTION AMOUNT ERROR

54 XML Redirect Integration Guide > Appendix D: Acquirer response codes 54 Card message value Status Code message value Statue 57 ILLEGAL TRANSACTION REFUSED 68 TRANSACTION TIMED OUT ERROR 62 RESTRICTED CARD REFUSED 80 AMOUNT NO LONGER AVAILABLE, AUTHORISATION EXPIRED ERROR 63 SECURITY RULES VIOLATED REFUSED 92 CREDITCARD TYPE NOT PROCESSED BY ACQUIRER ERROR 75 SECURITY CODE INVALID REFUSED 94 DUPLICATE REQUEST ERROR ERROR 76 CARD BLOCKED REFUSED - - Table 22: ISO 5853 response codes

55 XML Redirect Integration Guide > Appendix E: CVC/CVV and AVS 55 Appendix E: CVC/CVV and AVS Security Code (CVC/CVV) and Address Verification (AVS) checks help you to authenticate a transaction by comparing information entered by the shopper during the payment process with details held by the card issuer. You can examine the results of the check by sending an XML order inquiry for each order. For more information, see the Order Modifications and Order Inquiries Guide. The Worldpay payment service only carries out CVC/CVV and AVS checks on valid XML code. Testing CVC/CVV You can simulate the outcome of CVC/CVV checks using the codes in the table below: CVC/CVV code Simulated scenario Left blank NOT SUPPLIED BY SHOPPER 111 NOT SENT TO ACQUIRER 222 NO RESPONSE FROM ACQUIRER 333 NOT CHECKED BY ACQUIRER 444 FAILED 555 APPROVED Table 23: Testing CVC/CVV You can simulate the outcome of CVC/CVV checks for American Express, using the codes in the table below: CVC/CVV code Simulated scenario Left blank NOT SUPPLIED BY SHOPPER 1111 NOT SENT TO ACQUIRER 2222 NO RESPONSE FROM ACQUIRER 3333 NOT CHECKED BY ACQUIRER 4444 FAILED 5555 UNKNOWN 6666 APPROVED Table 24: Testing CVC/CVV for American Express Testing AVS You can simulate the outcome of AVS checks (on the billing address), using the codes in the table below:

56 XML Redirect Integration Guide > Appendix E: CVC/CVV and AVS 56 AVS code Simulated scenario Left blank NOT SUPPLIED BY SHOPPER 1111 NOT SENT TO ACQUIRER 2222 NO RESPONSE FROM ACQUIRER 3333 NOT CHECKED BY ACQUIRER 4444 FAILED 5555 UNKNOWN 6666 APPROVED Table 25: Testing AVS

57 XML Redirect Integration Guide > Appendix F: Test card numbers 57 Appendix F: Test card numbers You can use the following credit / debit card numbers to test transactions in the test environment only. When using test cards, you can specify an expiry date up to seven years in the future. The test cards do not have a card verification code and issue number. For more information about testing your XML Redirect integration, see Testing in the XML Redirect model on page 43. Test card numbers Card type Test card number Airplus American Express Cartebleue Dankort Diners and Discover card JCB Laser and Maestro and MasterCard and Visa , and Visa Debit and Visa Electron (UK only) Visa Purchasing Table 26: Test card numbers

58 XML Redirect Integration Guide > Appendix G: XML error codes 58 Appendix G: XML error codes The list of XML error codes is as follows: 1. Internal error, a general error. 2. Parse error, invalid XML. 3. Invalid number of transactions in batch. 4. Security error. 5. Invalid request. 6. Invalid content, occurs when XML is valid but content of XML is not. 7. Payment details in the order element are incorrect. V.me by Visa error code. There is also a V.me by Visa specific error code (also numbered error code 7): 7. Connection to V.me failed. For more information about structuring XML messages, see Structure of an XML Redirect order on page 19. Example: Error code 1. Internal error, a general error <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE paymentservice PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//en" " <paymentservice version="1.4" merchantcode="mymerchant"> <reply> <error code="1"><![cdata[iinternal error]]></error> </reply> </paymentservice> Example note: Code example 31: Error code 1. Internal error, a general error The error code is highlighted in red. Internal errors originate with the Worldpay payment service, and are usually addressed quickly. If you encounter an internal error, we recommend that you try submitting the XML message again after a brief period. Example: Error code 2. Parse error, invalid XML XML message posted empty <?xml version="1.0" encoding="utf-8"? <!DOCTYPE paymentservice PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//en" " <paymentservice version="1.4" merchantcode="mymerchant"> <reply> <error code="2"><![cdata[empty body in message]]></error> </reply> </paymentservice> Code example 32: Error code 2. Parse error, invalid XML

59 XML Redirect Integration Guide > Appendix G: XML error codes 59 Example note: The error code is highlighted in red. The error above indicates that the body of the XML message posted was empty. This error is also returned when the content length has been set incorrectly (too few characters have been specified). Incorrect / missing DOCTYPE declaration <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE paymentservice PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//en" " <paymentservice version="1.4" merchantcode="mymerchant"> <reply> <error code="2"><![cdata[missing DOCTYPE declaration]]></error> </reply> </paymentservice> Example note: Code example 33: Error code 2. Parse error, invalid XML The error code is highlighted in red. The example error above indicates that the XML code sent to Worldpay does not contain the required doctype declaration. This is used by our payment service to determine what kind of information is being sent. Example: Error Code 4. Security error <?xml version="1.0"?> <!DOCTYPE paymentservice PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//en" " <paymentservice version="1.4" merchantcode="mymerchant"> <reply> <error code="4"><![cdata[security Violation.]]></error> </reply> </paymentservice> Example note: Code example 34: Error code 4. Security error The error code is highlighted in red. The error code above usually indicates one of the following: There is a difference between the merchant code used to set up the connection and that referred to in the XML message. A connection has been attempted from an unregistered IP. You are submitting to an inactive environment (usually because you have only activated the test environment, and are attempting to submit to production).

60 XML Redirect Integration Guide > Appendix G: XML error codes 60 Example: Error Code 5. Invalid request <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE paymentservice PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//en"" <paymentservice version="1.4" merchantcode="mymerchant WPACC "> <reply> <orderstatus ordercode="123456"> <error code="5"><![cdata[duplicate Order]]></error> </orderstatus> </reply> </paymentservice> Example note: The error code is highlighted in red. Code example 35: Error code 5. Invalid request Each ordercode has to be unique. In the example above the merchant tried to post an order with the ordercode to our payment service. However, this order for the merchant already exists in the Worldpay database. A simple way to make an ordercode unique is to use a date/time-stamp, an incremental number or a combination of both. Example: Error Code 7. Payment details in the order element are incorrect <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE paymentservice PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//en" " <paymentservice version="1.4" merchantcode="mymerchant WPACC "> <reply> <orderstatus ordercode="1112"> <error code="7"> <![CDATA[Invalid payment details : Expiry date = 01/2002]]> </error> </orderstatus> </reply> </paymentservice> Example note: Code example 36: Error code 7. Payment details in the order element are incorrect The error code is highlighted in red. The example above shows a payment that has been refused because the expiry date occurs in the past. Example: Error Code 7. Connection to V.me by Visa failed The following XML example shows an error code 7 specific to V.me by Visa. This error occurs as a result of a failed connection with V.me by Visa:

61 XML Redirect Integration Guide > Appendix G: XML error codes 61 <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE paymentservice PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//en" " <paymentservice version="1.4" merchantcode="demo"> <reply> <orderstatus ordercode="test123"> <error code="7"> <![CDATA[Gateway Error: Cannot initialise V.me payment]]> </error> </orderstatus> </reply> </paymentservice> Example note: The error code is highlighted in red. Code example 37: Error code 7. Connection to V.me by Visa failed

62 XML Redirect Integration Guide > Appendix H: Changes to the guide 62 Appendix H: Changes to the guide Revision Release date 6.0 November September November October September August 2014 Changes Updated: Added: Updated: Added: Updated: Added: Updated: Added 5.3 July 2014 Added: Updated: 5.2 April 2014 Updated: Names of the types of Hosted Payment Pages. Information about the Hosted Payment Pages. Appendix C ISO country codes topic removed incorrect note. References to the Best Practice Guide (various chapters and sections) References to the SEPA Integration Guide (various sections) for ELV and Direct Debits in The Netherlands Moved Changes to the guide from Introduction on page 5 to this appendix MasterPass information Use HTTPS to Connect on page 14 A note to The order element on page 19 on how shoppers should have cookies enabled on their web browsers New Worldpay template applied to the entire guide. Minor rewording throughout the guide. Recurring payments information. Iframes security information. Shoppers should have cookies enabled. XML login information. Password length changed. Added information to Chapters 2 and 4 about the requirement from VISA that MCC 6012 merchants collect and send additional information

63 XML Redirect Integration Guide > Appendix H: Changes to the guide 63 Revision Release date 5.1 January December August March December March 2012 Changes Updated: Updated: Added: Updated: Updated: Updated: Added: 4.4 July 2012 Updated: Added: 4.3 May 2012 Updated: 4.2 April 2012 Updated: about the shopper. Information about the MAC secret password to emphasise the use of both alphanumeric characters and symbols. Guide rewritten and restructured. New template applied. Information about the V.me by Visa digital wallet service. Test card numbers. Payment method codes. Information about alternative payment methods was moved to the Alternative Payment Methods Guide List of alternative payment methods. Maximum and minimum amounts. Information about mandatory and optional fields for alternative payment methods. Information about transaction statuses returned in pendingurl. List of alternative payment methods. Maximum and minimum amounts. Added information about querying payment reference and list of banks for offline bank transfers. Payment method codes. Test card numbers.

64 XML Redirect Integration Guide > Appendix H: Changes to the guide 64 Revision Release date 4.1 March October 2011 Changes Added: Updated: 3.0 July 2011 Updated: StatementNarrative element. Alternative Payment Method codes. Payment pages chapter. Style and formatting for Worldpay rebrand. Table 27: Changes to the guide

65 XML Redirect Integration Guide > Contact us 65 To find out more, get in touch with your Relationship Manager or: Worldpay All rights reserved. Worldpay, the logo and any associated brand names are all trademarks of the Worldpay group of companies.