Quick start (Hosted)
Prerequisite: You need a test account before you can start.
Once you have a test account, follow these steps to make your first basic test payments:
Your Implementation Manager (or support contact) should have given you:
- A Merchant Code (or codes)
- An installation id (or ids)
- A Merchant Administration Interface Username and Password
Compatible devices and browsers
Our hosted payment pages are tested on a number of the latest devices and browsers regularly. This ensures they're up to date with the latest operating system versions and features.
For iOS and Android devices we support the native browser, the most recent operating system, and the last major operating system release at the point of testing.
Get your credentials
Log in to the test Merchant Administration Interface (MAI): https://secure-test.worldpay.com/sso/public/auth/login.html?serviceIdentifier=merchantadmin
Click ACCOUNT, then select Profile from the top menu.
- Note your New Username for the connection.
- Click the pencil icon () next to XML Password.
- Enter your new password and click Save XML Password.
Restrict IP addresses
You can restrict connections to your test account by specifying a number of IP addresses or ranges that your account can be accessed from. To do this:
- Click Integration.
- Go to the Merchant Environment tab, and click New Test IP to add a new IP address (or range).
Best practice: Send messages to fully qualified domains
Don’t send messages to specific IP addresses, as these can change, leading to a break in communications – sometimes we need to move to different IP addresses in our range to communicate with you.
Connect to Worldpay
To process payments through Worldpay you must:
- Use a secure connection. We recommend that you use Transport Layer Security v1.2 (TLS v1.2), however as a minimum you should use TLS v1.1
- Use basic authentication (the New Username and XML Password as created above)
- Use content type “text/xml"
Create payment request
You interact with Worldpay using XML messages. All messages should conform to the Worldpay
Set up your platform
Set up your platform for submitting XML messages to Worldpay’s payment service.
Note: The Worldpay payment service only accepts incoming XML messages if the originating IP address is registered for the merchant code in the message. For more information about registering and managing multiple IP address ranges, see the
The test URL to send XML messages to is: https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp
Example XML order
Here's a basic example of the data submitted for a card test payment. Before you send it you need to change the
merchantCode to your own, and be aware that each payment requires a unique
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//Worldpay//DTD Worldpay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"> <paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE"> <!--Enter your own merchant code--> <submit> <order orderCode="YOUR_ORDER_CODE" installationId="1234567"> <!--installationId identifies your Hosted Payment Page--> <description>YOUR_DESCRIPTION</description> <!--Enter a description useful to you--> <amount currencyCode="GBP" exponent="2" value="5000" /> <orderContent><![CDATA[AMOREDETAILEDDESCRIPTIONOFYOURORDERCONTENTCANGOHERE]]></orderContent> <paymentMethodMask> <include code="ALL" /> </paymentMethodMask> <shopper> <shopperEmailAddress>firstname.lastname@example.org</shopperEmailAddress> </shopper> <shippingAddress> <address> <address1>47A</address1> <address2>Queensbridge Road</address2> <address3>Suburbia</address3> <postalCode>CB94BQ</postalCode> <city>Cambridge</city> <state>Cambridgeshire</state> <countryCode>GB</countryCode> </address> </shippingAddress> <billingAddress> <address> <address1>47A</address1> <address2>Queensbridge Road</address2> <address3>Suburbia</address3> <postalCode>CB94BQ</postalCode> <city>Cambridge</city> <state>Cambridgeshire</state> <countryCode>GB</countryCode> </address> </billingAddress> </order> </submit> </paymentService>
The response to this order
In response, we send a redirect URL to the payment page:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"> <paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied in the order--> <reply> <orderStatus orderCode="ExampleOrder1"> <!--The orderCode you supplied in the order--> <reference id="YourReference">https://payments-test.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=NGPPTESTMERCH1%5Ejsxml3835829684&Ticket=00146321872957902pqKhCTUf0vajKCw-X5HqZA</reference> </orderStatus> </reply> </paymentService>
With the redirect URL you can go to the payment page and send the values shown in
Errors are displayed in our response like this:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.WorldPay.com/paymentService_v1.dtd"> <paymentService version="1.4" merchantCode="ExampleCode1"> <!--The merchantCode you supplied originally--> <reply> <orderStatus orderCode="ExampleOrder1"> <!--Not present for parse or security violation errors--> <error code="2"> <![CDATA[Invalid address: Postal code is missing or empty.]]> </error> </orderStatus> </reply> </paymentService>
Below are the more typical errors when connecting up for the first time. For other common error codes, see
Error Code 401 - authentication error
The basic authentication has failed which means the username and/or password was wrong.
Error Code 2 - Parse error, invalid XML
Your XML is invalid. The XML description will indicate what the problem is.
Error code 4 - security violation
The Merchant code you supplied in the XML does not match the username and password used to authenticate
You have submitted the message from an IP address that is outside the registered list (if one is set)
Error Code 5 - invalid order details
The contents of the
<order> element are invalid. Check the error message within the CDATA tag to determine the exact cause.
Error Code 5 - Invalid installation id
The contents of the
<installationId> element are invalid, or do not match the identification code used for your custom Hosted Payment Page configuration.