INSTRUCTIONS

Directing customers to WorldPay
Recurring charges
MD5 signing
Postback
Putting it all together

SEE ALSO
MAINTAINER
COPYRIGHT
VERSION

NAME

GT::Payment::Remote::WorldPay - WorldPay payment handling

CAVEATS

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.

SYNOPSIS

    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
    }

DESCRIPTION

This module is designed to handle WorldPay payment processing using WorldPay's ``Select Junior'' system and callback.

REQUIREMENTS

GT::CGI is the only requirement, however GT::MD5 is required in order to use the md5_signature function.

FUNCTIONS

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

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: param takes a GT::CGI object from which WorldPay postback variables are read.
on_valid: 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.
on_cancel: 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.
password: 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.
on_invalid_password: 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.
on_recurring
on_recurring_failed: 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.

md5_signature

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.

INSTRUCTIONS

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.

Directing customers to WorldPay

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:

instId: Your WorldPay Installation ID. Example: 1234
currency: The currency of the purchase. Example: GBP
desc: A description of the purchase. Example: Blue T-Shirt, Medium
cartId: A reference you assign to help you identify the purchase. Example: 10a0491.
amount: The total cost of the purchase. Example: 25.35

Recurring charges

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.

futurePayType: Should contain the value ``regular'', unless using ``Limited FuturePay Agreements,'' which will work but is not described here.
option: 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.
startDate: 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.
startDelayUnit: 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.
startDelayMult: 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.
noOfPayments: This number of payments that will be made. Leave as 0 or unset for unlimited.
intervalUnit: 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.
intervalMult: 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.
normalAmount: This must be set for option 0 and option 1, but cannot be set for option 2.
initialAmount: 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

MD5 signing

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.

Postback

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.

Putting it all together

The typical way to implement all of this is as follows:

Get necessary merchant information (instId, currency, callback password, and MD5 password).
Once the customer has selected what to purchase, generate a cartId (a random MD5 hex string works well - but do not use the MD5 signature!), and generate the MD5 signature.
Store the cartId somewhere (i.e. in the database).
Make a form with all the necessary fields that submits to WorldPay.
Set up the necessary callbacks (at least 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().
For a valid payment, do whatever you need to do for a valid payment, and store some record of the payment having been made (storing at least the cartId, the transId, and the futurePayId is strongly recommended). Use the CGI parameter 'cartId' to locate the order (i.e. in the database). It's recommended that you check Appendix A of the ``Select Junior Integration Guide'' for all available parameters.

MAINTAINER

Jason Rhinelander

COPYRIGHT

VERSION

Revision: $Id: WorldPay.pm,v 1.5 2004/02/26 16:55:39 jagerman Exp $

This module is designed for version 4.4 of the Select Junior payment integration.