Google Checkout
API
Jingsong Wang
Arpril 2, 2007
1
Agenda
Why
 How to use
 How to integrate

2
Agenda
Why
 How to use
 How to integrate

3
Why Google Checkout

Sell more.

Spend less.

Grow your business.
4
Why Google Checkout (cont..)

Customers, You

Google Checkout is a fast, convenient checkout process that
complements your existing process

until 2008, FREE..
5
Benefits

Attract more leads.

Convert more leads into sales.

Process sales for free.

Protect yourself from fraud.
6
Example
<form method="POST" action="https://sandbox.google.com/checkout/cws/v2/Merchant/1234567890/checkoutForm"
accept-charset="utf-8">
<input type="hidden" name="item_name_1" value="Peanut Butter"/>
<input type="hidden" name="item_description_1" value="Chunky peanut butter."/>
<input type="hidden" name="item_quantity_1" value="1"/>
<input type="hidden" name="item_price_1" value="3.99"/>
<input type="hidden" name="ship_method_name_1" value="UPS Ground"/>
<input type="hidden" name="ship_method_price_1" value="10.99"/>
<input type="hidden" name="tax_rate" value="0.0875"/>
<input type="hidden" name="tax_us_state" value="NY"/>
<input type="hidden" name="_charset_"/>
<input type="image" name="Google Checkout" alt="Fast checkout through Google"
src="http://sandbox.google.com/checkout/buttons/checkout.gif?merchant_id=1234567890&w=180&h=46&style=white&
variant=text&loc=en_US" height="46" width="180"/>
</form>
7
8
Agenda
Why
 How to use
 How to integrate

9
Sign In/Sign Up page
10
Place Order
11
Order Confirmation
12
Agenda
Why
 How to use
 How to integrate

13
How to integrate

HTML APIs

XML APIs
14
How to integrate
1. Go to http://sandbox.google.com/checkout/sell/ to set up test
accounts in the Google Checkout Sandbox service.

Create your buyer account at http://sandbox.google.com/checkout.
 Create your merchant account at http://sandbox.google.com/checkout/sell/.
15
How to integrate (cont)
2. Go to http://checkout.google.com/sell/signup to sign up for a
Google Checkout merchant account
16
How to integrate (cont)
3. Sign in to your test merchant account at
https://sandbox.google.com/checkout/sell to locate your Merchant
ID and your Merchant Key.
17
How to integrate (cont)
4. Add a Google Checkout button to the checkout pages on your
online store.
18
How to integrate (cont)
5. Modify the code for your online store so that the form containing
the Google Checkout button also submits information about your
customer's order.
19
HTML
20
Sending Checkout API Requests to
Google


In your development environment:
https://sandbox.google.com/checkout/cws/v2/Merchant/[[Merchant
ID]]/checkoutForm
In your production system:
 https://checkout.google.com/cws/v2/Merchant/[[Merchant ID]]/checkoutForm
21
Checkout API

Query key strings

Item Parameters
 item_name_# * - The parameter value identifies the name of the item.
 item_description_# * - The parameter value provides a description of the
item.
 item_quantity_# - The parameter value identifies how many units of a
particular item are included in the customer's shopping cart.
 item_price_#* - The parameter value identifies the price of the item.
 item_currency_# - The parameter value identifies the currency for the item
price. The default value is USD (U.S. dollars).

Shipping Parameters…

Tax Parameters…
22
<form method="POST"
action="https://sandbox.google.com/checkout/cws/v2/Merchant/1234567890/checkoutForm"
accept-charset="utf-8">
<input type="hidden"
<input type="hidden"
<input type="hidden"
<input type="hidden"
name="item_name_1" value="Peanut Butter"/>
name="item_description_1" value="Chunky peanut butter."/>
name="item_quantity_1" value="1"/>
name="item_price_1" value="3.99"/>
<input type="hidden"
<input type="hidden"
<input type="hidden"
<input type="hidden"
name="item_name_2" value="Grape Jelly"/>
name="item_description_2" value="16 oz. bottle of Concord grape jelly."/>
name="item_quantity_2" value="1"/>
name="item_price_2" value="4.49"/>
<input type="hidden" name="ship_method_name_1" value="UPS Air"/>
<input type="hidden" name="ship_method_price_1" value="19.99"/>
<input type="hidden" name="ship_method_us_area_1" value="CONTINENTAL_48"/>
<input type="hidden" name="ship_method_name_2" value="UPS Ground"/>
<input type="hidden" name="ship_method_price_2" value="10.99"/>
<input type="hidden" name="ship_method_us_area_2" value="FULL_50_STATES"/>
<input type="hidden" name="tax_rate" value="0.0875"/>
<input type="hidden" name="tax_us_state" value="NY"/>
<input type="hidden" name="_charset_"/>
<input type="image" name="Google Checkout" alt="Fast checkout through Google"
src="http://sandbox.google.com/checkout/buttons/checkout.gif?merchant_id=1234567890
&w=180&h=46&style=white&variant=text&loc=en_US" height="46" width="180"/>
</form>
23
Viewing Order Statuses in the
Merchant Center

financial-order-state

fulfillment-order-state
24
25
26
27
XML
28
Integration

Modify the code for your online store:

Your code needs to create an XML document containing information about the
items in your customer's shopping cart

The XML will also contain information about the shipping options that the
customer can select and the taxes that should be added to the order

Your code will need to encrypt the XML document and embed the encrypted
value in the form that contains the Google Checkout button
29
Integration (cont)

In your development environment:


<form method="POST"
action="https://sandbox.google.com/checkout/cws/v2/Merchant/[[Merchant-ID]]/checkout">
In your production system:

<form method="POST"
action="https://checkout.google.com/cws/v2/Merchant/[[Merchant-ID]]/checkout">
30
Google Checkout Buttons
31
32
When the customer clicks the
Google Checkout button

Two methods to send information about the customer's order to
Google so that the customer can complete the purchase.

You can configure your form to submit directly to Google Checkout. If you choose
this option, you must add code to your site that constructs an XML document
containing information about the customer's order as well as information about
your shipping options and tax policies. You will then encode the XML document
and embed it in the form that displays the Google Checkout button.

You can configure your form to submit to a page on your site that will then create
an XML document containing information about the order. Your application will
then post the XML to Google using an HTTP POST request. Google will then
respond to your request with a Google Checkout URL where your customer can
complete the order, and you will redirect the customer to that URL.
33
Integration Options

Level 1 Integration - Shopping Cart Integration

Level 2 Integration - Order Processing Integration
34
Level 1 Integration –
Shopping Cart Integration

By implementing the Checkout API, you will have completed a Level
1 Checkout integration.

At this integration level, you will receive new order notifications via
email. You can then manage orders using the Merchant Center, a
Google application that lets you track orders from your web browser.
35
Level 2 Integration –
Order Processing Integration

The Notification API enables Google to inform merchants of new orders
submitted through Google Checkout or to send updates for existing orders.
As such, the Notification API allows merchants to modify their systems to
automatically receive order information from Google Checkout.

The Order Processing API provides functions that let merchants change
an order's status or add information to an order. Thus, the Order Processing
API lets merchants modify their systems to automatically update Google
Checkout orders.

To implement these APIs, you must create a web service that sends and
receives XML messages about new orders and order status updates
36
Processing an Order

(This process flow describes the first method, in which the order
information is embedded in the form that displays the Google
Checkout button. When the customer clicks the Google Checkout
button, the customer's browser will submit the order directly to
Google. )
37
Processing an Order (cont..)

The first stage in the process explains how to send shopping cart
information to Google Checkout. These steps are the same for Level
1 and Level 2 integrations.

The second stage of the process describes the order fulfillment
process.

If you have completed a Level 1 integration, you will complete the
second set of steps through the Merchant Center. If you have
completed a Level 2 integration, you can modify your internal order
processing systems to handle these steps. You can also opt to use
the Merchant Center for these steps.
38
Processing an Order (cont..)
1. Your customer selects items on your website.





Create a checkout shopping cart for the buyer's items as an XML structure.
Create a signature for the shopping cart using the HMAC_SHA1 function.
Base64-encode the cart.
Base64-encode the signature.
Put the cart and signature into a Google Checkout button form.
Note: If you choose the second method of implementing the Checkout API, these steps will be
replaced by the steps in the Submitting Server-to-Server Checkout API Requests
2. After your customer completes the order through Google Checkout, you process the order and ship
items to the customer.





Receive the new order notification.
Charge the order.
Add tracking information to the order.
Mark the order shipped .
Archive the order.
39
Create a checkout shopping cart
40
Checkout API


Checkout API requests send order information from a merchant's website to
Google, enabling a customer to complete an order using Google Checkout.
The <checkout-shopping-cart> element is the root tag for Checkout API
requests. This tag contains three subtags.
 <shopping-cart>
 <checkout-flow-support>
 optional <order-processing-support> element contains information about
how Google should process an order or how Google should convey
data about the order to the merchant. Currently, you would only use this
element if you wanted to instruct Google Checkout to send an
<authorization-amount-notification> after a customer submits a new
order and Google authorizes the customer's credit card.
The Processing an Order and Submitting Server-to-Server Checkout API
Requests sections of this document explain two different processes for
creating and submitting Checkout API requests.
41
Create an HMAC-SHA-1 signature

You must create an HMAC-SHA-1 signature, a cryptographically
secure value that enables Google to verify that the XML in the
<checkout-shopping-cart> structure was not altered before Google
received it.

Most development environments provide a function for creating
HMAC-SHA-1 signatures. To create the signature, call the
appropriate function, passing the <checkout-shopping-cart> XML
structure and your Merchant Key as parameters to the function.
42
Base64-encode the cart

After you create the signature, base64-encode the <checkoutshopping-cart> XML structure
43
Base64-encode the HMAC-SHA-1
signature

Using the same function that you called to encode the shopping cart,
base64-encode the HMAC-SHA-1 signature that you created in step
ii.
44
Add the order information and signature to a
Google Checkout button form

Add those values to the form on your page that displays a Google
Checkout button.
45
46
Receive the new order notification

When a customer submits an order, Google can notify you that the
new order has been submitted. There are two ways to receive new
order notifications:

Google can send email notifications for new orders. If you have not
implemented the Notification API, Google will automatically email you to
notify you have new orders.

Level 2 only: If you have implemented the Notification API, Google will
send a new-order-notification to inform you of the new order. The
notification will include the order shopping cart as well as other
transaction details such as the shipping method, shipping address and
taxes for the order.
47
48
Add tracking information to the
order

After shipping the order, you can add shipment tracking information
that will appear on the buyer's account page. There are two ways:

Log in to your Merchant Center account.

Level 2 only: If you have implemented the Order Processing API, you can add
tracking information by sending an add-tracking-data command to Google.
49
Mark the order shipped

Once the order has been shipped, you can also mark it Shipped in
the Merchant Center and on the buyer's account page. There are
two ways:

Log in to your Merchant Center account.

Level 2 only: If you have implemented the Order Processing API, you can send
a deliver-order command to Google.
50
Archive the order

After the order has been delivered, you can archive the order to
remove it from the list of active orders that appears on the Orders
page of the Merchant Center. (This step is optional; you do not need
to archive orders.) There are two ways:

Log in to your Merchant Center account.

Level 2 only: If you have implemented the Order Processing API, you can send
an archive-order command to Google. The XML below shows a sample archiveorder command:
51
Typical Order Flow

Figure 1: An order is placed by a customer, accepted by the
merchant and the customer is charged.

Figure 2: The merchant processes the order, ships the order, and
then archives the order after it has been delivered to the customer.
52
53
54
Credit Card Authorization and
Capture

After a new order is confirmed by the buyer, Google will attempt to authorize the
buyer's credit card for the full order amount. If the authorization succeeds and the
order passes Google's risk checks, the order's financial order state will be updated to
CHARGEABLE. If the authorization fails, Google will email the buyer to request a
new credit card. If the buyer supplies a new credit card, Google will try to authorize
that card. However, if the buyer does not supply a new credit card within 72 hours
after the email is sent, Google will cancel the order.

After payment has been authorized, you can charge the order for any amount up to
the authorized amount. You can continue charging an order until all authorized funds
have been captured.

Merchants can instruct Google Checkout to automatically charge orders as soon as
they become chargeable.
55
Authorizing Payment before
Shipping Items

When a customer places an order, the new order will appear in your Inbox in your Merchant
Center account. When the order is submitted, the listing for that order in your Merchant Center
Inbox will display a status of Reviewing. As long as the order's status is Reviewing, you will not be
able to charge the customer for the order. During this time, Google Checkout will authorize the
customer's credit card for the amount of the purchase.

After the payment has been authorized, the order's status will update from Reviewing to New. You
should not ship the ordered items to the customer until the order's status has updated to New.
After that time, you will also have the option to charge the customer for the order. To charge the
customer, you would click the Charge button that appears next to the order in your Merchant
Center Inbox.

Level 2 only: If you have implemented the Order Processing and Notification APIs, you should not
ship ordered items unless you have received the following three notifications for the order.



The new order notification
The risk information notification
The order state change notification informing you that the order's financial-order-state has been updated to
CHARGEABLE
56
Others..
Reauthorizing a Customer's Credit Card
 Buyer Refund Request

57
Posting XML Messages to Google


https://sandbox.google.com/checkout/cws/v2/Merchant/1234567890
/checkout
https://checkout.google.com/cws/v2/Merchant/1234567890/checkout
58
Guidelines for XML API Requests

Specify UTF-8 encoding by including the following line at the start of each XML API request:


<?xml version="1.0" encoding="UTF-8"?>
To include the XML reserved characters &, <, and > in an XML element value, you must encode
the characters as hexadecimal numeric character references.

The following table shows the numeric character references for these characters:You can use all other UTF8 characters directly.

Google will not render HTML tags that you include in XML element values. If you pass HTML tags,
such as in the <item-name> and <item-description> elements, Google will remove the HTML tags
and display the text without formatting.

Unless otherwise noted, string elements in Google Checkout are not limited to any particular
length.
59
Internationalization

Google Checkout includes the following internationalization-ready
features:

All XML messages between you and Google Checkout use UTF-8 (Unicode)
encoding.

Time/date values use the ISO 8601 standard, which specifies time as an offset
from UTC.

All money elements have a currency attribute.
60
Immediate (Synchronous)
Responses to Posts

When you post an API request to Google, Google Checkout
evaluates your XML request to ensure that it is valid and returns a
synchronous HTTP response to indicate whether your request is
valid.

A valid request must conform with the Google Checkout XML
schema and must also request a legitimate action.
61
Immediate (Synchronous)
Responses to Posts (cont..)

If your request is valid, Google will return a <request-received> response.

If your request is not properly formed or requests an invalid status change, Google
Checkout will return an <error> response to your request
 Invalid argument
 Invalid state change
62
Security Requirements and
Precautions

How you can format HTTP request headers to use HTTP Basic Authentication:

Set the Authorization header by using your Merchant ID as the username and
your Merchant Key as the password. To obtain the header value for an order
processing request, take your Merchant ID and then append a colon (:) and your
Merchant Key. Finally, base64-encode the entire value. Google uses the same
process to create the authorization headers for notifications. As such, when you
receive a notification from Google, you can base64-decode the authorization
header to confirm that the notification is valid.

Include the Content-Type header with the value application/xml; charset=UTF8

Include the Accept header with the value application/xml; charset=UTF-8
63
Security Requirements and
Precautions (cont..)
Example:

Merchant ID is 1234567890
Merchant Key is HsYXFoZfHAqyLcCRYeH8qQ,

Base64-encode the value 1234567890:HsYXFoZfHAqyLcCRYeH8qQ

The base64-encoded value would appear in the request header:
64
Source
HTML API Developer's Guide

http://code.google.com/apis/checkout/developer/google_checkout_html_api.html
XML API Developer's Guide

http://code.google.com/apis/checkout/developer/index.html
Thanks
65