Beyond Scripting... Professional Programming for the Web.

Google Checkout

Tip of the week for June 30, 2006 discusses how Lasso can be integrated with Google Checkout. The tip includes tags which assemble and transmit a shopping cart to Google so site visitors can check out using this new payment option.


Introduction

Google Checkout is a new payment option for the Web which offers several different levels of integration so it can be used with a wide variety of eCommerce sites. Google Checkout handles the actual credit card processing on its own secure server and then makes the orders available through its on line merchant interface so they can be fulfilled.

More information about Google Checkout can be found at the following Web site. If you are interested in using this service you should read the terms of use and the information about merchant fees carefully.

<http://checkout.google.com/sell>

- The simplest integration is through Buy It Now buttons which can be generated directly in the merchant interface. These one shot buttons can be used for sites which only have a few items to sell.

- Your site can assemble the items that a visitor wants to buy into a shopping cart and then send the visitor to Google for checkout. The look and feel of your Web store is all your own, but Google Checkout handles the details of payment. This is the method which is explained in this tip of the week.

- More advanced integration options allow Google Checkout to call back to your Web site in order to processing shipping calculations, custom tax calculations, custom coupons, and more. More advanced integration will be covered in a future tip of the week.

Complete information about the API used for each level of integration can be found in the following Web page.

<http://code.google.com/apis/checkout/developer/index.html>


Source Code

The example for this tip of the week can be found at the following URL.

<http://support.omnipilot.com/article_files/google_checkout.lasso>

The source code for this page can also be viewed.

<http://support.omnipilot.com/article_files/google_checkout.lasso?source=true>

Finally, the [Google_Checkout] tag can be downloaded from TagSwap.

<http://www.tagswap.net/google_checkout>


Background

This tip explains how a very lightweight method of communication can be used to transmit shopping cart information to Google Checkout. This method relies on Lasso and your custom code to assemble a list of items which the visitor wants to buy. When the visitor is ready to check out the items are assembled into an XML document descrbing the cart.

Your Google Checkout merchant key and ID are used to transmit the XML cart contents to Google in one of two ways.

- Preferably the site visitor is shown an HTML form which displays an image like that shown below. When the site visitor clicks on the image they are taken to Google Checkout where they can complete their transaction.



- Alternately, you can submit the cart contents to Google using an HTTP post (through [Include_URL]). The result will be an XML document which includes a URL that the site visitor is redirected to. The net effect is the same. The site visitor is taken to Google Checkout where they can complete their transaction.


Sandbox Test Account

Before you begin you need a Google merchant ID and key. For testing purposes you can get a "sandbox" merchant ID and key at <http://sandbox.google.com/sell>. You should sign up using a valid, but non-gmail email address. The account which is created will allow you to test the Google Checkout service, but no actual transactions will be performed. Note that you don't need to enter real address information, but it should appear valid (two letter state, five digit zip, etc.).

You should also create a test account which you will use to make purchases. This must use a different email address than the account created above. You should again use a valid, but non-gmail email address. Create the test account at <http://sandbox.google.com/>. Again, you don't need to enter real information. You can use the following fake credit card numbers (only in the sandbox). The CVC for each should be a three digit number (or four for AmEx) and the expiration date can be any date in the future.

MasterCard 5555 5555 5555 4444
VISA 4111 1111 1111 1111
Discover 6011 1111 1111 1117
American Express 3782 8224 6310 005


Going Live

When you are ready to go live with your site you will need to sign up for a real Google Checkout merchant account at <http://checkout.google.com/sell>. You will receive a different merchant ID and key. These will need to be entered into your [Google_Checkout] tag and the -Sandbox parameter should be removed. Any testing should be done very carefully since actual credit charges will now be made!


Submitting a Cart

In the most basic workflow, the [Google_Checkout] tag is used to create a cart. The [Google_Checkout->AddItem] tag is used to add one or more items to the cart. And, finally, the [Google_Checkout->CheckoutForm] tag is used to show the Google Checkout button to the user. Note that this system isn't a complete shopping cart. The idea is that you will use your own shopping cart code to find out what items a site visitor wants to buy and then use the [Google_Checkout] type to format that order so it can be payed for through this service.

A [Google_Checkout] object is created using this code. The Merchant ID and Merchant Key must be those provided by Google. The -Sandbox parameter should be used when the site is being tested. The Edit URL is displayed so the visitor can return to your site after viewing their cart. The Continue URL is displayed after the visitor has checked out so they can return to your site. The expiration date controls how long this cart can be long. The example has the cart expire after one day.

[Var: 'mycart' = (google_checkout:
  -merchantid='963566791773926',
  -merchantkey='1234567890',
  -editurl='http://www.example.com/edit',
  -continueurl='http://www.example.com/continue',
  -shippingname='Pony Express',
  -taxes=(array: '98366'=0.085, 'WA'=0.070, 'all'=0.0),
  -sandbox=true,
  -expires=date->(add: -day=1) &)]

The shipping name controls how the shipping is described in the Checkout interface. This tag only allows one shipping method to be used so the description should be something like "UPS Ground" or "Media Mail". The Google Checkout API offers more shipping offers, but they are a topic for a more advanced integration than presented here.

Google Checkout has a complex algorithm for calculating taxes. The example shows one tax rate 8.5% is used for the zip code 98366, another tax rate 7.0% is used for Washington state, and no tax is charged for other addresses. Any zip code 02139, zip code with wildcard 02*, or state abbreviation MA can be used. The word 'all' represents all US shipping address, 'full' represents any address in the 50 states', and 'continental' represents any address in the 48 contiguous states. Rules should be listed in order from most specific to least specific.

At this point it does not appear that European or other addresses are being handled at all by Google Checkout.

Items are added using the [Google_Checkout->AddItem] tag. Each item has a name, description, price, and shipping cost. The quantity is how many of the item the visitor wants to buy. The price and shipping cost are multiplied by the quantity to get the total cost for the item. Two of these widgets would cost $319.98 with $20.00 shipping.

[$mycart->(additem: -name='My Widget',
  -description='My patented widget. A true original.',
  -price=159.99,
  -quantity=2,
  -shipping=10.00)]

Finally, the Checkout button is displayed. The checkout button can be small, medium (the default), or large.

[$mycart->(checkoutform: -Size='large')]

That's it! The above three tags create a shopping cart with one item in it and allow the visitor to check out at Google Checkout. The tax rate is determined by the visitor's shipping address.


[Google_Checkout] Type

See the source code of the example included with this tip for additional details about the tags that are included in the [Google_Checkout] type. There are several additional options which are not covered in this brief description.

<http://support.omnipilot.com/article_files/google_checkout.lasso?source=true>


Shopping Cart Format

The core of the Google Checkout API is the XML format in which your site visitors shopping cart data will be transmitted. A simple cart is shown below. This cart has one item "My Widget" which costs $159.99 and two of these are requested. The [Google_Checkout] data type performs all of this formatting for you so you don't need to learn this XML format. The cart can contain as many items as you need.

<?xml version="1.0" encoding="UTF-8"?>
<checkout-shopping-cart xmlns="http://checkout.google.com/schema/2">
  <shopping-cart>
    <items>
      <item>
        <item-name>My Widget</item-name>
        <item-description>My patented widget. A true original.</item-description>
        <unit-price currency="USD">159.99</unit-price>
        <quantity>2</quantity>
      </item>
    </items>
  </shopping-cart>

The remainder of the cart contains information about the cart itself. The possible shipping methods are described. The [Google_Checkout] type handles flat shipping which has a single price for the total amount of shipping for all of the items in the cart combined. It is also possible to embed tax tables and much more information in the XML of a cart.

  <checkout-flow-support>
    <merchant-checkout-flow-support>
      <shipping-methods>
        <flat-rate-shipping name="Pony Express">
          <price currency="USD">20.0</price>
        </flat-rate-shipping>
      </shipping-methods>
    </merchant-checkout-flow-support>
  </checkout-flow-support>
</checkout-shopping-cart>


Checkout Form

The standard checkout form which is created by the [Google_Checkout->CheckoutForm] tag is shown below. The form action is a page on Google's server which includes a reference to the Merchant ID. The "cart" input includes the Base64 encoded XML content of the cart. The "signature" input includes the HMAC SHA1 hash of the XML content of the cart using the Merchant Key. Finally, the image input uses an image referenced from Google's server.

<form action="https://sandbox.google.com/checkout/cws/v2/Merchant/1234567890/checkout" method="post">
  <input type="hidden" name="cart" value="PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZG ... =" />
  <input type="hidden" name="signature" value="AyJPNwgVXt2h5QqAh69pJiD5fDE=" />
  <input type="image" name="Google Checkout" alt="Fast checkout through Google"
    src="http://sandbox.google.com/checkout/buttons/checkout.gif?merchant_id=1234567890&..." height="46" width="180" />
</form>


Checkout Redirect

The [Google_Checkout] type also supports an alternate method of sending the site visitor to Google for checkout. The [Google_Checkout->PostCart] tag submits the cart data to Google using [Include_URL]. The cart data is sent as the -PostParams of the submission. The Merchant ID and Merchant Key are used as the username and password for the submission. The result includes a URL which the site visitor is redirected to so they can complete checkout.

It is prefered to use the Checkout Form described above when possible, but the redirect method may be used if it integrates into your site better.


Notes

This tip includes an implementation of [Encrypt_HMAC]. This tag will be included in a future version of Lasso. The tag can be used to generate the keyed hash message authentication code for a given input and password. The tag works with many different digest formats including MD5 and SHA1. See the description in the source code for more details.


More Information

More information about all of the tags used in this example can be found in the Lasso 8.5 Language Guide or in the online Lasso Reference <http://reference.omnipilot.com/>.