cult3

Customising WorldPay and creating a Callback

Aug 01, 2012

Table of contents:

  1. The files we are going to need
  2. Customising the WorldPay payment pages
  3. tableHead.html and tableFoot.html
  4. Creating a WorldPay callback
  5. Conclusion

In this week’s instalment of the integrating WorldPay series, we’ll be looking at the files you need to create and upload to WorldPay, customising the payment process and creating a Callback to sync back to your server.

Once you have successfully taken a payment through WorldPay, you need to present the customer with a confirmation and further details of their order. If you are integrating WorldPay into ecommerce software, a Callback allows you to send data about the transaction back to your database.

This is the third and final instalment of the integrating WorldPay series. If you missed the previous tutorials, take a look at Getting started with WorldPay integration and Integrating WorldPay into a database driven website.

The files we are going to need

In order to customise the payment process and user experience, WorldPay allows you to upload a number of files to their server. Some of the files allow you to add extra information to the pages, whilst others allow you to show your company’s confirmation message and logo during and at the end of the process.

Here is a list of the files we are going to need. I’ll explain each of them in this tutorial.

  • footer.html
  • head.html
  • header.html
  • paymentBottomFields.html
  • paymentBottomFields.html
  • paymentTopFields.html
  • resultC.html
  • resultY.html
  • stylesheet.css
  • tableFoot.html
  • tableHead.html

Customising the WorldPay payment pages

Once you have sent your customer to WorldPay’s secure server, they are presented with a payment page that they need to complete in order to successfully make the purchase.

By default, WorldPay’s payment pages are incredibly ugly and use massively outdated markup. WorldPay also does not allow you to alter the payment pages and so you are stuck with having to use their table based form.

WorldPay does allow you to use your own CSS file however, so we can use some CSS magic to considerably improve the look and feel of the payment process.

stylesheet.css

The first file we’re going to make is the stylesheet that will hold all of our CSS code.

Here’s a stripped back CSS file that you can use to get started customising your WordPay payment pages.

/* Reset */
body,
div,
h1,
h2,
h3,
h4,
h5,
h6,
p,
ul,
ol,
li,
dl,
dt,
dd,
img,
blockquote {
  margin: 0;
  padding: 0;
  border: 0;
}

body {
  font-family: verdana;
  font-size: 62.5%;
  text-align: center;
}

a:link {
  color: #000;
}

a:visited {
  color: #000;
}

a:hover {
  color: #000;
}

table {
  width: 100%;
}

h1 {
  font-weight: normal;
}

h2 {
  font-weight: normal;
}

input,
select,
textarea {
  background-color: #ededed;
}

textarea {
  resize: none;
  font-family: verdana;
}

To really start refining the way your payment pages look, you can hook on to a couple of CSS classes and Id’s that are used in WorldPay’s markup.

header.html and head.html

These two files allow you to place extra code at the top of your payment pages. For example, you might want to mockup your company’s website header, or put your company’s logo or corporate branding at the top of the page so the payment pages aren’t completely different to your website.

Here are these two files to get you started.

header.html

<div id="content"></div>

Here I’m just going to wrap the payment form in a div. This allows you to style it however you want.

head.html

<!- additional HTML head items ->

I’m just going to leave this file empty.

Next we have the footer file. Again, use this file to wrap your payment pages in your company’s corporate branding, mockup your website’s footer or place links to your customer support pages.

</div><!-/content->

tableHead.html and tableFoot.html

These two files are used at the top and the bottom of the table that displays the payment form. Here is some standard code to get your started. Notice how you can use wpdisplay tags in your files. This allows to to edit certain parameters from your control panel.

tableHead.html

<table class="container" cellpadding="<wpdisplay disp=wp.container.border.width>" cellspacing="0" align="center">
  <tr>
    <td>
      <!- the main content table ->
      <table class="containercell" cellspacing="<wpdisplay disp=wp.container.cellSpacing>" cellpadding="<wpdisplay disp=wp.container.cellPadding>">
        <tr>
          <td class="title" colspan="2">
            <!- page title ->
            <h1>
              <wpdisplay msg=payServ.name>
                </h1>
              <!- end page title ->
              </td>
        </tr>
        <!- end tableHead.html ->

tableFoot.html

</table>
</td>
</tr>
</table>

Payment fields files

The payment fields files allow to to add additional fields to the WorldPay form. This allows to you collect additional information from the user.

In Getting started with WorldPay integration I showed you how to Custom Parameters using the prefixes “MC_“ or “C_“.

To add extra fields, simply use the following HTML code.

<input type="hidden" name="MC_customerAge" value="" />

The payment fields files are called:

  • paymentTopFields.html
  • paymentMiddleFields.html
  • paymentBottomFields.html

You can also use these three files to display additional HTML in your page, it doesn’t have to be extra fields of the table.

The results pages

The next two pages we will be looking at are resultY.html and and resultC.html. These two pages display confirmation of either a successful payment of a cancelled payment. Personally, I don’t really use these as I always use a callback to sync back to my server. However, even if you plan to use a callback, you must still create these two files as fallbacks should something go wrong.

resultY.html

This page is used to confirm a successful transaction.

<wpdisplay file=header.html>
  <table class="container" cellpadding="<wpdisplay disp=wp.container.border.width>" cellspacing="0" align="center">
    <tr>
      <td>
        <!- the main content table ->
        <table class="containercell" cellspacing="<wpdisplay disp=wp.container.cellSpacing>" cellpadding="<wpdisplay disp=wp.container.cellPadding>">
          <tr>
            <td class="title">
              <!- page title ->
              <h1>
                <wpdisplay msg=resultY.name>
                  </h1>
                <!- end page title ->
                </td>
          </tr>
          <tr>
            <td valign="top" align="left">
              <wpdisplay item=banner default="">
                </td>
          </tr>
          <wpdisplay payment=authentication-check contents=true>
            <tr>
              <td class="authenticationbanner">
                <table width="100%" cellspacing="0" cellpadding="0" border="0">
                  <tr>
                    <td valign="middle" align="left">
                      <wpdisplay msg=card.authenticationPromotion arg1="|msg=card.authentication.<wpdisplay payment=paymentType>" arg2="|msg=card.authenticationPromoURL.<wpdisplay payment=paymentType>" stylize=1.instr>
                        </td>
                    <td valign="top" align="right" style="width:81px;">
                      <a href="<wpdisplay msg='card.authenticationPromoURL.<wpdisplay payment=paymentType>'>" target="_blank" title="<wpdisplay msg=newwindow.title>">
                        <img src="<wpdisplay disp='card.authentication.<wpdisplay payment=paymentType>'>" style="width:81px; border:0px;" alt="<wpdisplay msg='card.authentication.<wpdisplay payment=paymentType>'>" />
                      </a>
                    </td>
                  </tr>
                </table>
              </td>
            </tr>
          </wpdisplay>
          <wpdisplay file=tableFoot.html default="</table></td></tr></table>">
            <wpdisplay file=footer.html default="</td></tr></table></td></tr></table></td></tr></table>">

Notice the use of the wpdisplay tags to display information about the transaction and to include the header and footer files.

resultC.html

<wpdisplay file=header.html>
  <table class="container" cellpadding="<wpdisplay disp=wp.container.border.width>" cellspacing="0" align="center">
    <tr>
      <td>
        <!- the main content table ->
        <table class="containercell" cellspacing="<wpdisplay disp=wp.container.cellSpacing>" cellpadding="<wpdisplay disp=wp.container.cellPadding>">
          <tr>
            <td class="title">
              <!- page title ->
              <h1>
                <wpdisplay msg=resultC.name>
                  </h1>
                <!- end page title ->
                </td>
          </tr>
          <tr>
            <td valign="top" align="left">
              <wpdisplay item=banner default="">
                </td>
          </tr>
          <wpdisplay file=tableFoot.html default="</table></td></tr></table>">
            <wpdisplay file=footer.html default="</td></tr></table></td></tr></table></td></tr></table>">

Putting it all together

You now have all the files you need to start customising your WorldPay payment process. Next, upload all of the files to your WorldPay admin section and begin testing your payment process to customise it to how you want it.

Creating a WorldPay callback

Your callback is a file that sits on your server and enables you to sync the transaction confirmation details with your records.

This would be incredibly useful for instance, if you needed to create a list of confirmed payments so you could ship items. By creating an automated system, you will save yourself a lot of time because you won’t have to log into WorldPay and export a list of details every day.

Once the customer has submitted their payment details and the transaction has been either confirmed or denied, your callback file will be pinged with a POST request.

The POST request contains all of the details of the transaction as well as any additional parameters you sent through the process. This allows you to update you records with the transaction data to show if an order completed or not. It also gives you an opportunity to record your customer’s data if you did not do so before hand.

The callback file is incredibly valuable to your business, so it is important to get it right. Here is how you to make it.

Display the data

The first thing to is to display exactly what data WorldPay is sending you on the page. By having an exact list of what data is available to you, it will make creating the rest of this file a doddle.

So create a file on your server called callback.php and copy and paste the URL into the callback address field in your WorldPay installation admin panel.

Next copy and paste the following code, upload it to your and do a test transaction so you reach your callback confirmation page.

echo "<pre>";
print_r($_POST);
echo "</pre>";

You should see a list of the data that WorldPay is sending you. Make a note of the parameter names as this will come in handy.

Now delete all the code from your callback file.

Finally, make a list of all the parameters you want to use in your callback script.

Create a new class

Next we’re going to create a class to save all the data we wish to use in our script.

// class definition
class worldpay_response
{
}

For each data attribute you wish to use, create the variable, like this:

public $transaction_id = null;

Next, create the __construct() function, like this:

public function __construct() {
    $this->transaction_id = $_POST['transId'];
}

Again do this for all of the parameters you wish to use.

Finally, instantiate a new instance of the class, like this:

$wp_response = new WorldPay_Response();

Your code should look like this (but with a lot more parameters!):

// class definition
class worldpay_response
{
    public $transaction_id = null;

    public function __construct()
    {
        $this->transaction_id = $_POST["transId"];
    }
}

$wp_response = new WorldPay_Response();

The callback password

The next thing to do is to set a callback password in your WorldPay admin section. Your callback file should only ever be accessed with a WorldPay request. When WorldPay requests your callback file they will include the password that you set in your installation settings. This allows you to deny access to your callback file to every request other than WorldPay’s.

In my WorldPay installation, I set my callback password to “guacamole”.

To block access without a password, use an if statement like this. If the password is not set, simply send the request to your 404 page.

if ($wp_response->callback_password == "guacamole") {
    // Success!
} else {
    header("Location: /404");
}

Display confirmation

Your callback page will also be used to display confirmation messages to your customer. This is doing the same job as the resultY.html land resultC.html files you created earlier.

Your callback file can also be used to update your database with confirmation of a successful sale, or to record that a client did not complete their purchase.

To display a message of confirmation or notification of an incomplete payment, or to run code depending on the outcome of the trnsactions, we use an if statement to create a fork in the road.

if ($wp_response->transaction_status == "Y") {
    // Payment confirmed
} elseif ($wp_response->transaction_status == "C") {
    // Payment cancelled
} else {
    // Incase something went wrong
}

As you can see in the above code, a transaction_status of “Y” means the payment was successful, “C” means the customer cancelled the transaction and we use an else statement to catch if anything has went wrong.

Within each of these branches you can run whatever code you need to update your database or send invoices or shipping details to your customers.

The final code

<WPDISPLAY FILE="header.html">
// class definition
class worldpay_response {
    // define properties
    public $transaction_id = null;

    // constructor
    public function __construct() {
        $this->transaction_id = $_POST['transId'];
    }
}

$wp_response = new WorldPay_Response();

// If password is correct
if ($wp_response->callback_password == "guacamole") {
    // Content based upon transaction status
    // Y = Successful transaction
    // C = Cancel transaction
    if ($wp_response->transaction_status == "Y") {
        echo "<h1>Payment confirmed</h1>";
        echo "<p>Hi " . $wp_response->name . " your payment was successful."
    } elseif ($wp_response->transaction_status == "C") {
        echo "<h1>Payment cancelled</h1>";
        echo "<p>Hi " . $wp_response->name . " your payment was cancelled and you have not been charged."
    } else {
        echo "<h1>Something went wrong</h1>";
        echo "<p>Hi " . $wp_response->name . ", I'm sorry, something went wrong."
    }
}
?>
<WPDISPLAY ITEM="banner">
<WPDISPLAY FILE="footer.html">

Conclusion

And there you have it! You should now have everything you need to set up your payment process with WorldPay. WorldPay is a little bit behind the times in the online payment industry, but it is a firm choice for many clients. Hopefully these three tutorials will enable you to quickly be able to pick up WorldPay and integrate it into your website or web application.

If you have any questions, please feel free to leave a comment.

Philip Brown

@philipbrown

© Yellow Flag Ltd 2024.