METHODS

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

There are no other dependancies.