NAME
Business::WorldPay::Junior - Perl module to handle WorldPay Junior for payment services, including callback services.
SYNOPSIS
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;
}DESCRIPTION
A simple module that handles transaction tracking and callback management for the WorldPay Junior service - card payment facility.
METHODS
new
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. }
register
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.
valid_callback_host
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 192.168.234.12.
If you have specified that there should be a callback password check this in your script.
callback
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.
authorised
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 }
DEPENDANCIES
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.
AUTHOR
Jason Clifford, <jason@jasonclifford.com>
LICENSE
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.
SEE ALSO
The WorldPay support website (at http://support.worldpay.com/) for more details about the Select Junior service.
perl.