Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Junior(3)	      User Contributed Perl Documentation	     Junior(3)

       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

       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

       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

       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.


perl v5.32.1			  2022-03-27			     Junior(3)


Want to link to this manual page? Use this URL:

home | help