Checkout API Overview
The Checkout API consists of four major components:
- Cart posting API
- Notifications API
- Order processing API
- Merchant-calculation callback API
Cart Posting API
This is the only mandatory component of the API. That is, if you as a merchant want to implement the bare minimum of integration, this is it. Cart posting is the mechanism through which a customer is taken from the merchant's website to Google, and by which the customer's shopping cart contents come with her.
There are two ways of posting carts to Google. The preferred approach when using ASP.NET is this:
- Display the Google Checkout button to the customer on a web page.
- When the customer clicks the button, compose a <checkout-shopping-cart> XML document with the customer's items in it.
- Do a server-to-server post from the merchant's server to Google.
- Google will reply with a <checkout-redirect> XML document.
- Redirect the customer to the URL found in the <checkout-redirect> document.
This is all that is needed for Checkout integration. The merchant will be notified by email when orders are placed. He can see all orders when he logs in to Google Checkout. From there he can also charge orders, mark them as shipped, cancel orders, and issue refunds.
The other approach is to encrypt and sign the shopping cart XML and send it to the customer's browser as part of a web form. The customer will then post that form to Google. This is easy to implement in classic ASP, PHP, JSP, etc. But as ASP.NET pages post forms back to themselves, the first approach is cleaner to implement with .NET. This second approach will not be discussed further in this article.
Processing orders manually is fine if you have a dozen orders per day. But it quickly becomes hard to manage as your order volume grows. If you have larger volume than that, you probably have an order database as well. And you want Checkout orders to automatically be copied into that database, rather than having to type them in by hand. This is where notifications come in.
As a merchant, you can specify a URL to which Google will post XML messages when significant events occur. These significant events are:
- A new order is placed.
- An order has gone through Google's fraud review.
- An order's state has changed.
- An order has been charged.
- An order has been refunded.
- There has been a chargeback on an order.
The new order notification contains XML for the order, including items, billing address, and shipping address. You can use this notification to copy the order data into your own order database. The other notifications can be used to keep order state in your database in sync with order state in Google's database.
Order Processing API
Implementing the Notification API eliminates the need for manually keeping your order database in sync with Google's. But you would still have to click a button on Google's website for every order you want to charge or cancel. If you already have an order management system, you probably want to charge Checkout orders automatically when your system marks them as ready for charging.
This is where the order processing API comes in. With this API, you can:
- Charge an order.
- Refund an order.
- Cancel an order.
- Mark an order as "Processing" (rather than "New").
- Assign an order number to an order.
- Mark an order as "Delivered."
- Add a carrier's tracking number to an order.
- Send email to the customer.
- Archive and unarchive orders.
Merchant-Calculation Callback API
This is the final, and least used, optional component. You need it if you have complex shipping rules or tax rules, or if you accept certain types of coupons or gift certificates.
This API works by posting XML to a URL of your choice while the customer is on Google's Checkout page. For example, if the customer enters a gift certificate code, Google will post XML to your system and you are expected to reply with a result indicating whether the gift certificate code was valid, as well as its dollar value. You can also request that the customer's shipping address be sent to your system in the same manner, so you can calculate shipping cost and sales tax.
Because the merchant-calculated API is quite complex, it will be the subject of its own article.
Design Considerations for the .NET Sample Code
Google provides sample code in several different languages for integrating with Checkout. This sample code is meant to give merchants a running start when integrating their own systems with Checkout.
When writing the .NET sample code, I tried to take these factors into account:
- The code should be clear and easy to read. This would not only make merchants' lives easier; it would also enable the open source community to take over the code eventually.
- The code should not go against the grain of how ASP.NET works. For example, in ASP.NET form pages post back to themselves. This means that posting carts by sending a form to the customer's browser that she then posts to Google would not be supported.
- The code should be easy to maintain. That meant the code should not compose XML by laborious string concatenations. Instead, all the code that composes and parses XML should be generated from the XSD file provided by Google. That would make it easy to regenerate the code when the API changes.
- The sample code will change, either because bugs are fixed, or because the underlying API changes. As new versions of the code become available, merchants should be able to drop them in easily. All the merchant-specific logic should live in the code calling the library, not inside it.
- While the XML API is clearly described in the public Dev Guide, it is a lot of reading and few developers will remember it all. The sample code should provide a higher level of abstraction than the XML itself.
- Many merchants using .NET, especially those on platforms built on top of .NET, are still on older versions of the .NET framework. The sample code should run on versions 1.1, 2.0, and 3.0 of the framework.
- Finally, the sample code should only use tools and features available in the .NET framework as provided by Microsoft--that is the only component we are certain all developers have access to. In hindsight, I may have applied this principle too inflexibly when excluding the NUnit test cases from the publicly available sample code.