Getting started with WorldPay integration
Jul 18, 2012
Table of contents:
It is now easier than ever to take payments online through a website or web application without the hassle of setting up secure, compliant infrastructure.
WorldPay allows anyone with a Merchant Account to instantly take payments from clients or customers through a website. WorldPay is backed by The Royal Bank of Scotland and accepts most major credit and debit cards.
Whilst WorldPay is a safe and reliable way to start taking payments online, the documentation that is provided to set everything up leaves a lot to be desired.
WorldPay’s documentation is spread over a number of different PDFs, HTML pages and sections of their website. Much of the documentation is not clear or structured incoherently and there are crucial aspects that are completely missing. With that being said, WorldPay’s technical support team in their UK based call centre is top draw, so don’t let that put you off using them as a payment processor.
This will be the first in a series of posts that will document my entire collective knowledge of integrating WorldPay as a payment processor for your website. I’ll try and cover every aspect and every detail you will need to get going, and I’ll highlight the most important parts of the process that left me scratching my head.
There is far too much to cover in a single post. So I’ll be breaking it down over a couple of weeks.
To keep up to date with this series, follow us on Twitter, Facebook, Google Plus or RSS.
How does WorldPay work?
Before I get into the technical aspects of how to set up WorldPay, it’s important that you understand how it works. This will not only make it easier to understand the rest of this guide, but you will also have a much better understanding for fully integrating it into your website.
WorldPay integration basically has three parts:
- You send WorldPay data about the sale (price + additional data)
- The customer enters their payment details into a secure form on WorldPay’s server
- The payment is processed and either accepted or denied
I’ll explain exactly how each of these parts work, and what you need to do to set them up further on in the guide under each appropriate section, but for now all you need to understand is this three step process.
What is FuturePay
Once you get your WorldPay account up and running, you can start to take one off payments for products on your website. FuturePay is a way to set up recurring payments that can be configured in a variety of ways depending on your needs.
Think of FuturePay as a way to set up an online subscription service.
If you want to use FuturePay on your website, you need to request it to be added to your account as an additional service.
Once you have FuturePay installed on one of your WorldPay installations, you can then start to take recurring payments.
FuturePay requires you to send additional data to WorldPay when processing a payment which I will cover later in this post.
Preparing your website
This section of the guide will largely depend on how you have built your website or what Content Management System or eCommerce software you are using. I’ll try and describe the process in general terms so you understand what you need to do, then I’ll give you a solid example of how I build this section.
As I mentioned above, the first step in integrating WorldPay is to prepare the data that you wish to send about the transaction. There are a number of mandatory parameters and a lot more additional ones that you can use as part of your transaction process.
The easiest way to send data to WorldPay is to use a form with a POST method.
So the first thing to do is create a HTML form.
<form action="https://secure.worldpay.com/wcc/purchase" method="POST"></form>As you can see, we are using the POST method to send data to the WorldPay secure payment address.
Testing mode
Testing is an integral aspect of getting a process like this to work correctly and because we are dealing with money, we don’t want to be actually making real transactions. To ensure our form is in test mode, add the following hidden input to your form.
<input type="hidden" name="testMode" value="100" />You are probably wondering how you are going to fully test transactions without entering payment details. WorldPay provides a number of test card numbers for you to use to test your code. Bookmark that page as it will come in handy later on.
Mandatory Parameters
For every transaction request you send to WorldPay, there are 4 parameters that must be included or your request will fail.
The mandatory parameters are…
instId
This is your installation ID. You can use WorldPay on many different websites through the same account. Each website you wish to use WorldPay needs to have it’s own installation, and therefore a unique ID that is provided by WorldPay.
To include your instId, use this line of code.
<input type="hidden" name="instId" value="Your installation ID " />cartId
The next mandatory parameter is a cartId. A cartId is just a reference to identify this particular form.
To add a cardId, use the following line of code.
<input type="hidden" name="cartId" value="Your ID for the product " />amount
The next mandatory parameter is the total cost of this transaction. For example, “10.00”. This is obviously a bit of a security risk, but fear not, I’ll cover that soon. For now, all you need to know is you must put the total cost of this transaction as a parameter in the form.
To add the amount parameter, use this line of code.
<input type="hidden" name="amount" value="The cost of the product " />currency
Finally, the last mandatory parameter is the currency of the transaction. To choose the correct currency, use the 3 character code.
To add the currency parameter, add the following line of code to your form.
<input type="hidden" name="currency" value="currency code e.g. GBP, USD " />Finally add a submit button to send the form.
<input type="submit" value="Buy" />Congratulations, you should now have a fully functional form that can transmit transaction data to WorldPay.
To recap, you should have the following form. To try it out, enter your details into the values of each of the inputs, save the file as a .html file and load it into your browser. Click the submit button to test it out. If you have everything set up correctly, you should see a WorldPay form ready to take your payment details. If something went wrong, WorldPay should give you a description of what you are missing.
Here’s the full form code:
<form action="https://secure.worldpay.com/wcc/purchase" method="POST">
<input type="hidden" name="testMode" value="100" />
<input type="hidden" name="instId" value="Your installation ID " />
<input type="hidden" name="cartId" value="Your ID for the product " />
<input type="hidden" name="amount" value="The cost of the product " />
<input type="hidden" name="currency" value="currency code e.g. GBP, USD " />
<input type="submit" value="Buy" />
</form>The form we have built so far is just a very basic way of transmitting data to WorldPay. It is the process in it’s most basic state.
This is great for getting started, but you will obviously want to build upon it to create a fully functional payment process.
Optional parameters
The first step towards building a better payment process is to start taking advantage of the optional parameters. WorldPay requires a customer to enter their name, address and other details into their secure server in order to process a payment. You can either allow a customer to enter the details into WorldPay, or you can collect the details on your site and then send the details to WorldPay with the transaction data. This means when they get to the WorldPay form, all of their data is already entered into the system.
The main advantage of this approach is you can capture the customer’s data and create an account on your website for repeat purchases and future transactions.
Here is a run down of all of the optional parameters you can choose to include in your form (and therefore capture on your site) if you wish.
These fields are either mandatory or optional. Mandatory in the sense that the customer has to fill them in once they reach WorldPay. You don’t have to include them, but it means the customer doesn’t have to fill it in once they reach WorldPay.
addressLine1 - Mandatory.
addressLine2 - Optional.
addressLine3 - Optional.
town - Mandatory.
postcode - Can be optional or mandatory at your discretion.
country - Mandatory.
desc - A 255 character description of the product to be used on the WorldPay pages and subsequent emails. I don’t believe this is mandatory, but it would be weird not to set it.
authMode - Allows you to choose full-auth or pre-auth depending on your preferences. Pre-auth payments allow you to reserve an amount on the customer’s card without actually taking it. This is useful if you are unsure when the item will be shipped and so you don’t want the headache of having to cancel and refund a payment.
testmode - We used this in the previous example, but it’s worth explaining in full. Use a value greater than 0 for a test result. You can also specify the test result you want by entering REFUSED, AUTHORISED, ERROR, or CAPTURED in the name parameter. This is useful for testing the different outcomes of your process.
authValidFrom and authValidTo - Allows you to set timestamps to restrict transactions or offers between certain time periods.
name - The customer’s full name. Mandatory.
tel - Mandatory.
fax - Optional.
email - Mandatory. Used to send payment notification emails.
fixContact - Allows you to send the customer details and not allow the user to edit them once they get to the WorldPay page.
hideContact - If you are sending the full contact details of the customer, this parameter allows you to hide them once they reach the WorldPay form.
hideCurrency - Allows you to hide the currency option.
lang - Allows you to set the shopper’s language choice.
withDelivery - Allows you to display shipping input boxes that must be filled in by the customer.
There are also a few other minor parameters that I won’t be covering.
Custom parameters
Custom parameters allow you to define and transmit any data you want when sending your transaction details. This allows you to display extra information on the result pages, or match up data once the user has successfully completed their payment.
For example, you might want to transmit the user’s ID from your site, so when they return to your website you know who they are.
There are three types of customer parameters:
- Custom “C_” parameters are available for use in the result pages, but are not available to your Payment Notifications script.
- Custom “M_” parameters are available to your Payment Notifications script, but are not available for use in the result pages.
- Custom “MC_” and “CM_” parameters are available to both your Payment Notifications script and the result pages.
So if you wish to send the customer’s ID through WorldPay and get it out the other end, you would use a MC_ parameter, like this…
<input type="hidden" name="MC_customerId" value="123" />FuturePay parameters
As I mentioned earlier in this guide, FuturePay is WorldPay’s system for taking recurring payments. If you want to set up a recurring or subscription model, then FuturePay is what you will need.
In order to take FuturePay payments you need to include some additional parameters.
futurePayType - The value of this should be “regular”
option - Must be set to either 0, 1, or 2. These options relate to how the recurring payments will work.
<u>0</u> - With option 0, the individual payments for the duration of the agreement are at a fixed price. However, you can set an initial payment at any price.
For example, you can have an initial payment of £100 and then 5 payments of £20. At no point in the agreement can you change the £20 payments.
<u>1</u> - With option 1 you must set the normal payments at the start of the agreement and you can set an initial payment if you wish. During the course of the agreement you can adjust the recurring payment amounts.
<u>2</u> - With option 2 you do not set the payment amount when the agreement is made. This option allows you to take payments for the duration of the agreement but not on a recurring basis. For example, it is an agreement to bill the customer whenever it is needed, rather on a set schedule.
startDate - yyyy-mm-dd - Date on which the first payment will be made. This can not be set for the day of the agreement it has to be at some point in the future. With option 2 it must be at least 2 weeks into the future.
startDelayUnit - One digit: 1-day, 2-week, 3-month, 4-year - Unit of the delay between when the agreement is created and when the first payment will be made. You only use this parameter if you have not set startDate.
startDelayMult - A number greater to or equal to 1. You must use this parameter and the previous one together in order to set a start delay. The numbers are multiplied together. for example. The following code would express a start date delay of 3 weeks.
<input type="hidden" name="startDelayUnit" value="2" />
<input type="hidden" name="startDelayMult" value="3" />noOfPayments - Number. The number of payments which will be made under the agreement. If you want the agreement to be unlimited, either don’t set it or set it to 0.
intervalUnit - One Digit: 1-day, 2-week, 3-month, 4-year. The unit of the interval between payments.
intervalMult - Number. The interval unit multiplier. The actual interval between payments is intervalUnit multiplied by intervalMult. The same logic as startDeley unit and mult.
initialAmount - The amount of the initial payment - if not set first payment will be for the normal amount. For example, 100.00.
normalAmount - Amount of normal payments. For example, 20.00
Conclusion
That just about wraps up the basics of setting up your website to transmit transaction data to WorldPay. In the next couple of posts I’ll give you a complete working example that integrates with a database, security measures you must take, setting up the WorldPay files and creating a callback at the end of the process.
To keep up to date with this series, follow us on Twitter, Facebook, Google Plus or RSS.
