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
http://www.xml.org.
5.1 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" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="MYMERCHANT" version="1.4"> <reply> <orderStatus orderCode="T0211010"> <reference id="1234567">https://secure.worldpay.com/jsp/shopper/SelectPaymentMethod.jsp?orderKey= MYMERCHANT^T0211010</reference> </orderStatus> </reply> </paymentService>
Code example 15: XML response
Example notes:
The content is highlighted in red.
<reply> The redirect information is contained in the reply element.
orderCode The order code to match the response to the order in your back-office system.
<reference> 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:
https://secure-test.worldpay.com/jsp/shopper/SelectPaymentMethod.jsp? orderKey=MYMERCHANT^T0211010
5.1.1 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.
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.
5.1.2 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.
5.1.3 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
5.2.1 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 athttp://php.net/manuel/en/function.url
The Microsoft Developer Network athttp://msdn.microsoft.com/en- us/library/zttxte6w.aspx
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.
XML Redirect Integration Guide >5 Redirecting to the payment pages 33
5.2.2 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 639-1 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, seewww.iso.orgYou can also find out more about country codes inISO country codes on page 52.
5.2.3 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
Code example 16: bodyAttr
Example notes:
The content is highlighted inpurple.
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.
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:
https://secure.worldpay.com/servlet/HTTPSProxy?
Code example 17: HTTPS proxy string
5.2.4 fontAttr
The fontAttr attribute sets the font attributes of the payment method selection screen. &fontAttr=face%3D%22arial%22+color%3D%22white%22
Code example 18: fontAttr
Example notes:
The content is highlighted inpurple.
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).
5.2.5 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.