Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  BUSINESS::WORLDPAY::JUNIOR (3)

.ds Aq ’


Business::WorldPay::Junior - Perl module to handle WorldPay Junior for payment services, including callback services.



  use Business::WorldPay::Junior;
  my $wp = Business::WorldPay::Junior->new( db => worldpay,
                                                           dbuser => wpuser,
                                                           dbpass => wppass );

  my $cartId = undef;
  if ( ! $cartId = $wp->register(\%transaction) )
      die "whatever - " . $wp->errstr;
  # Send customer off to Worldpay for processing...
  # Get called as a result of the callback
  my %cb = $cgi->Vars;
  if ( ! $wp->valid_callback_host($cgi->remote_host) )
      # Security issue - callback can only be from valid WorldPay host
      die "Security warning " . $wp->errstr;
  if ( ! $wp->callback(\%cb) )
      # Invalud callback
      die "whatever - " . $wp->errstr;

  if ( ! $wp->authorised() )
      # No authorisation received...
      die "noauth - " . $wp->errstr;


A simple module that handles transaction tracking and callback management for the WorldPay Junior service - card payment facility.



To start using Business::WorldPay::Junior you need to initialise the module in your script using the new method like so:

use Business::WorldPay::Junior;

my $wp = Business::WorldPay::Junior->new( db => ’worldpay’,
dbuser => ’worldpay’,
dbpass => ’wppass’,
host => ’localhost’ );

The db, dbuser and dbpass parameters are compulsory and should be the database that the worldpay table is located within and the mysql username and password with select, insert and update privileges on that table.

Optionally you can specify a host parameter to point to the host where the database is located. If this is not specified it defaults to localhost.

Do remember to test that the call to new succeeded as if you have not correctly passed the required details it will fail. This does the trick nicely:

if ( ! $wp )
# deal with it. Note that there should be an error message in
# $Business::WorldPay::Junior::errstr detailing why it failed.


Once you have initialised the module you can carry on to either register a new transaction, process a callback or check whether a given transaction has already been authorised.

To register a new transaction you use the register method like so:

my $cartId = $wp->register(\%transaction_details);

As you can see the actual transaction details are passed as a reference to a hash. The hash typically looks like this:

my %transaction_details = ( amount => 12.50,
desc => A Test Transaction,
instId => ’99999’,
currency => ’GBP’,

The details above are the only ones that are necessary to register a new transaction and all correspond to the standard WorldPay parameters - do note that they are case sensetive.

The $cartId variable returned should be used for the WorldPay cartId parameter. It is generated by an auto-incrementing field in the database so it’s pretty much guaranteed to be unique for that database.

Once you have registered your transaction you should send the user to the WorldPay website for payment - I usually just print a simple page to the user informing them of the amount owing and what it is for with a simple Click here to pay button. It’s a simple HTML form.


To check that the source of the callback is authentic you simply call the valid_callback_host method like this:

if ( ! $wp->valid_callback_host($cgi->remote_host) )
# Invalid callback host - handle the error.
# You should probably bring this security violation to the attention of
# a real person within your organisation.

Note that remote_host is the CGI method so you need to have the CGI module loaded for this, which I’ve assumed you will as you are handling data provided by that means anyway.

Also note that this module assumes that you are not carrying out reverse resolution on connections to your web site so it expects a standard IPv4 address - ie something like

If you have specified that there should be a callback password check this in your script.


Like the register method, detailed above, the callback method expects you to pass the details via a reference to a hash. If you tell the CGI module that you want to use the functionality of cgi-lib - by using CGI with qw (:cgi-lib) as an arguement - you can make use of the CGI Vars method which is the easiest way to this this:

my %callback_data = $cgi->Vars; if ( ! $wp->callback(\%callback_data) )
# The data supplied in the callback is not valid
# You can get more information about the problem by calling
# $wp->errstr which will return an error string

The callback method only verifies that the data in the callback is correct and matches a registered transaction. It does not tell you whether the transaction was authorised or not.


To check whether a transaction was authorised by WorldPay use the authorised method like so:

my $cartId = $cgi->param(’cartId); if ( ! $wp->authorised($cartId) )
# This transaction was NOT authorised


This module requires MySQL for the backend data store and depends upon DBI and DBD::mysql to talk to it.

There are no other dependancies.


Jason Clifford, <>


This module is licensed under the terms of the Free Software Foundations Gnu Public License (GPL) version 2.

See the accompanying COPYING file for specific details of the license.

Note that you may not alter, copy or redistribute this module except in accordance with the terms of the GPL license.


The WorldPay support website (at for more details about the Select Junior service.


Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 JUNIOR (3) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.