GT::Payment::Remote::WorldPay - WorldPay payment handling
One thing to note about WorldPay is that its security system is a little weak - you can't trust a callback post as actually being genuine, unless you use the callback password feature - and even at that it is not a terribly secure solution. In this regard, other payment provides have much cleaner transaction systems. Another shortcoming of WorldPay is that its callback system is somewhat weak - it won't try to inform you very hard: it tries once, but if it doesn't connect it gives up and doesn't try again, making it entirely possible and likely that you will have to manually add (or confirm) missing payments at some point, so supporting at least manual payment approval of initiated payments is absolutely required.
use GT::Payment::Remote::WorldPay; use GT::CGI;
my $in = new GT::CGI;
GT::Payment::Remote::WorldPay->process( param => $in, on_valid => \&valid, on_cancel => \&cancel,
on_recurring => \&recurring, on_recurring_failed => \&recurring_failed, on_recurring_cancelled => \&recurring_cancelled,
password => "123", on_invalid_password => \&invalid_pw );
sub valid { # Update database - the payment has been made successfully. }
sub cancel { # Update database - the user has clicked the "Cancel" button, thereby # cancelling the payment. You should take note of the cancellation. }
sub on_recurring { # Update database - a recurring payment has been made successfully. }
sub on_recurring_failed { # Update database - a recurring payment has failed. }
sub on_recurring_cancelled { # Update database - either the customer or the merchant has cancelled # this recurring payment }
sub on_invalid_password { # Perhaps make a record - a payment callback was received without a # valid password }
This module is designed to handle WorldPay payment processing using WorldPay's ``Select Junior'' system and callback.
GT::CGI is the only requirement, however GT::MD5 is required in order to use the md5_signature function.
This module has only two functions. process()
does the work of actually
figuring out what to do with a postback, and md5_signature()
is used to
generate an MD5 signature for payment verification and security purposes. Both
functions can be imported into your package, and can be called as either method
or function.
process()
is the main function provided by this module. It can be called as
either a function or class method, and takes a hash (not hash reference) of
arguments as described below.
process()
should be called for WorldPay initiated postbacks. This can be set
up in your main CGI by looking for WorldPay-specific CGI parameters
('transStatus' is a good one to look for) or by making a seperate .cgi file
exclusively for handling WorldPay postbacks.
Additionally, it is strongly advised that database connection, authenticate,
etc. be performed before calling process()
to ensure that the payment is
recorded successfully. WorldPay will not attempt to repost the form data if
your script produces an error, and the error will be shown to the customer.
The param
argument, either on_valid
or
on_recurring
, and the password
options
are required. Using MD5 signing as well is strongly advised.
param takes a GT::CGI object from which WorldPay postback variables are read.
on_valid takes a code reference as value. The code reference will be called when a successful payment has been made. Inside this code reference you are responsible for setting a ``paid'' status for the order in question.
Takes a code reference to call in the event of the customer clicking the ``cancel'' button. Note that this is not sent if the user closes their browser, but only if they click ``cancel.''
You should record a cancelled payment in your application.
This is a password that the customer should set in the WorldPay Customer Management System, and provide to you. Without this password, WorldPay postbacks should not be considered secure.
This code reference will be called when the correct password is not present in the postback request. This will also be called if no password is provided.
In order to support recurring payments, you must at least define
on_recurring
. on_recurring
is called when a successful recurring payment
has been made. on_recurring_failed
is called for a failed recurring payment
(e.g. credit card declined). See
the Recurring charges section for more details.
Bear in mind that if you do not set up the on_recurring callback, recurring payments will be ignored.
The md5_signature()
function takes a password (this must be set for the
WorldPay account), and a list of values and generates an appropriate WorldPay
MD5 signature, which should be included as the ``signature'' field. See
the MD5 signing section for more details.
To implement WorldPay payment processing, there are a number of steps required in addition to this module. Basically, this module handles only the postback stage of the WorldPay payment process.
Full WorldPay ``Select Junior'' information is available from the ``Select Junior Integration Guide'' available from www.worldpay.com.
This is done by creating a web form containing the following variables. Your
form, first of all, must make a post
request to
https://select.worldpay.com/wcc/purchase
.
Required fields are as follows:
Your WorldPay Installation ID. Example: 1234
The currency of the purchase. Example: GBP
A description of the purchase. Example: Blue T-Shirt, Medium
A reference you assign to help you identify the purchase. Example: 10a0491
.
The total cost of the purchase. Example: 25.35
Additionally, in order to set up recurring payments, the WorldPay account must have ``FuturePay'' enabled, and then you need to use the following parameters.
The below parameters are used for the ``Regular FuturePay Agreements'' - there is also ``Limited FuturePay Agreements'' in which a maximum overall charge is set. For more information, see Repear Billing With FuturePay.
Should contain the value ``regular'', unless using ``Limited FuturePay Agreements,'' which will work but is not described here.
Should contain either 0, 1, or 2. 0 means the payment amount is fixed and cannot be changed. 1 means the payment is fixed, but can be changed to another amount at any point. 2 means the payment amount must be set before each recurring payment.
Value in the format: ``yyyy-mm-dd''. This should be the date on which the first future payment should be taken. Note that this is _NOT_ and CANNOT be today, but must be a value in the future. If using option 2, this value must be at least 2 weeks in the future.
One digit: 1: day, 2: week, 3: month, 4: year. Only used if startDate is not set. If using option 2, this value must be at least 2 weeks in the future.
The actual delay is obtained by multiplying this value by startDelayUnit. So, to start in three weeks, this would be ``3'', and startDelayUnit would be ``2''. Again, this is not used if startDate is specified. Must be >= 1 if set.
This number of payments that will be made. Leave as 0 or unset for unlimited.
One digit: 1: day, 2: week, 3: month, 4: year. The unit of interval between payments. This must be set unless noOfPayments is 1. If using option 1 or option 2, the minimum interval is 2 weeks.
The interval between payments is determined by this value multiplied by intervalUnit. So, to make payments every 1 month, this would be ``1'', and intervalUnit would be ``3''. Must be >= 1.
This must be set for option 0 and option 1, but cannot be set for option 2.
This can be used for option 0 or option 1, but cannot be set for option 2. If set, this overrides the amount of the first payment.
For FuturePay (recurring) payments, you still pass the required fields as normal, except for the amount field: amount can be passed as 0 or a value - if a value is specified, this will be treated as an immediate payment. So, for example, if you wanted to charge someone a monthly subscription of $10 starting today you would pass the following variables:
instId=1234 # (the merchant's installation reference here) amount=10 cartId=8456a9264q314 # (Some random ID here that you generate) currency=USD # (Whatever currency they are charging in goes here) desc=Subscription For Something Cool # (Description of subscription) option=0 normalAmount=10 startDelayUnit=3 startDelayMult=1 intervalUnit=3 intervalMult=1
Additionally, using WorldPay's MD5 signature feature is strongly recommended.
To enable this feature, provide a field ``signatureFields'', containing fields separated by ``:''. Although any fields can be used, ``amount:currency:cartId'' is recommended. Then, call:
my $md5 = GT::Payment::Remote::WorldPay::md5_signature( $password, $amount, $currency, $cartId );
$password should be a password provided by the user and known only to the user and WorldPay. The value returned should be passed as the ``signature'' variable.
This MD5 protection causes WorldPay to reject any faked payment requests and so is reasonably secure.
Before WorldPay postback notification can occur, you must instruct the user to enable the callback facility in the Customer Management System. Additionally, it is recommended that a proper URL to your CGI be specified there, or else pass along a ``MC_callback'' variable that points to the script _WITHOUT_ a leading http:// or https://. (e.g. MC_callback=www.example.com/callback.cgi).
Note that a WorldPay limitation prevents the callback protocol (http://) from being changed dynamically - whatever protocol is set for your callback URL in the Customer Management System will be used with the dynamic callback URL.
The typical way to implement all of this is as follows:
on_valid
and
on_valid
). If using a dedicated CGI script for WorldPay
callbacks, it should just call process(); otherwise, check for the CGI
parameter 'transStatus' and if present, call process().
http://support.worldpay.com - WorldPay Knowledge Base, containing many useful WorldPay manuals and instructions.
http://support.worldpay.com/kb/integration_guides/junior/integration/help/sjig.html - Select Junior Integration Guide, from which this documentation and module is primarily derived.
http://support.worldpay.com/kb/product_guides/futurepay/repeatbilling.html - Repeat Billing with FuturePay.
Jason Rhinelander
Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/
Revision: $Id: WorldPay.pm,v 1.9 2006/08/22 23:03:14 brewt Exp $
This module is designed for version 4.4 of the Select Junior payment integration.