- NAME
- CAVEATS
- SYNOPSIS
- DESCRIPTION
- REQUIREMENTS
- FUNCTIONS

- process

- INSTRUCTIONS

- Directing customers to 2CheckOut
- Postback
- Putting it all together

- SEE ALSO
- MAINTAINER
- COPYRIGHT
- VERSION

# 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:

- sid

      Your 2CheckOut account number

- total

  The total amount to be billed, in DD.CC format.

- cart_order_id

  A unique order id, which you should store to track the payment.

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

- card_holder_name
- street_address
- city
- state
- zip
- country
- phone

  The card holder's details.

- email

  The card holder's email address.

- ship_name
- ship_street_address
- ship_city
- ship_state
- ship_zip
- ship_country

  Shipping info - however, according to 2CheckOut, you must indicate that you want to take that you want to take down a seperate shipping and billing address on the Shipping Details page.

- demo

  Should be set to 'Y' if you want demo mode, omitted for regular transactions.

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

- order_number

  2CheckOut order number

- cart_order_id
- cart_id

  Your order number, passed back. Both variables are the same.

## 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 $