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 one function: process() does the work of actually figuring out what to do with a postback.

process

process() is the only 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 Look & Feel -> Secret Word). 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.

demo

Whether or not to initiate and accept demo transactions.


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/2co/buyer/purchase. See https://www.2checkout.com/documentation/UsersGuide2/third_party_carts/2co-system-parameters.html for a complete and up-to-date list of parameters that can be passed to 2CheckOut.

Required fields are as follows:

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

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

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:

  1. Get necessary merchant information (sid and secret keyword)
  2. 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).
  3. Make a form with all the necessary fields that submits to 2CheckOut.
  4. 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().
  5. 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).


SEE ALSO

http://www.2checkout.com - 2CheckOut website.

http://www.support.2checkout.com/deskpro/faq.php - 2CheckOut knowledgebase


MAINTAINER

Jason Rhinelander


COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/


VERSION

Revision: $Id: 2CheckOut.pm,v 1.5 2006/08/22 20:39:04 brewt Exp $