NAME

GT::Payment::Remote::2CheckOut - 2CheckOut payment handling

CAVEATS

2CheckOut has a pretty weak automated payment system - the security of the entire automated payment process hinges on your ``Secret Word'' (Admin -> Account Details -> Return -> Secret Word (near the bottom of the page)) - without it, there is no security at all. Another weakness in the system is that if your server is not reachable for whatever reason, the payment information would be lost. Payment providers like 2CheckOut and WorldPay would do well to learn from payment systems like that of PayPal - whatever can be said about other aspects of PayPal, they do have one of the nicest payment systems around - both from a developer and user's point of view.

Because of the security issue with not using the ``Secret Word'', this module requires that the secret word be used, even if other 2CheckOut systems may not. Additionally, the default secret word of ``tango'' is not allowed.

SYNOPSIS

    use GT::Payment::Remote::2CheckOut;
    use GT::CGI;

    my $in = new GT::CGI;

    GT::Payment::Remote::2CheckOut->process(
        param => $in,

        on_valid => \&valid,

        sellerid => "1234",
        password => "Some Good Secret Word"
    );

    sub valid {
        # Update database - the payment has been made successfully.
    }

DESCRIPTION

This module is designed to handle 2CheckOut payment processing.

REQUIREMENTS

GT::CGI and GT::MD5.

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 2CheckOut initiated postbacks. This can be set up in your main .cgi by looking for 2CheckOut-specific CGI parameters ('cart_order_id' is a good one to look for) or by making a seperate .cgi file exclusively for handling 2CheckOut postbacks.

Additionally, it is strongly advised that database connection, authenticate, etc. be performed before calling process() to ensure that the payment is recorded successfully. 2CheckOut will not attempt to repost the form data if your script produces an error, and the error will be shown to the customer.

param: param takes a GT::CGI object from which 2CheckOut 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. The cart_order_id CGI variable will have whatever cart_order_id you provided.
sellerid: This should be passed to seller number. This is needed, along with the password field below, to verify that the posted payment is a genuine 2CheckOut payment.
password: This is a ``Secret Word'' that the admin must set in the 2CheckOut admin area (under Account Details -> Return, near the bottom of the page). This field must be set in the admin, and passed in here. Note that the default value, ``tango'', is not allowed. Without this password, 2CheckOut postbacks should not be considered secure.

INSTRUCTIONS

To implement 2CheckOut payment processing, there are a number of steps required in addition to this module. Basically, this module handles only the postback stage of the 2CheckOut payment process.

Directing customers to 2CheckOut

This is done by creating a web form containing the following variables. Your form, first of all, should post to https://www.2checkout.com/cgi-bin/sbuyers/cartpurchase.2c.

Required fields are as follows:

sid


Your 2CheckOut account number

total

cart_order_id

The following parameters *may* be passed in, and will be available in the postback:

card_holder_name
street_address
city
state
zip
country
phone

email

ship_name
ship_street_address
ship_city
ship_state
ship_zip
ship_country

Shipping Details page

demo

In the postback CGI, you'll get back all of the billing and shipping variables listed above, plus:

order_number

cart_order_id
cart_id

Postback

Before 2CheckOut postback notification can occur, you must set up the postback (in 2CheckOut terminology, ``Routine''). This can be set from the Admin -> Shopping Cart -> Cart Details. You need to enable the payment routine, and set it to a CGI that you manage.

Putting it all together

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

Get necessary merchant information (sid and secret keyword)
Once the customer has selected what to purchase, generate a cart_order_id (a random MD5 hex string works well), and store it somewhere (i.e. in the database).
Make a form with all the necessary fields that submits to 2CheckOut.
Set up the on_valid callback. If using a dedicated CGI script for 2CheckOut callbacks, it should just call process(); otherwise, check for the CGI parameter 'cart_order_id' 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 cart_order_id and the order_number is strongly recommended). Use the CGI parameter 'cart_order_id' to locate the order (i.e. in the database).

MAINTAINER

Jason Rhinelander

COPYRIGHT

VERSION

Revision: $Id: 2CheckOut.pm,v 1.3 2004/01/13 01:35:18 jagerman Exp $