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="[Link] ac
cept-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="[Link]
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 [Link] to set up test ac
counts in the Google Checkout Sandbox service.

 Create your buyer account at [Link]

 Create your merchant account at [Link]

15
How to integrate (cont)
2. Go to [Link] to sign up for a Go
ogle Checkout merchant account

16
How to integrate (cont)
3. Sign in to your test merchant account at https://
[Link]/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 cu
stomer's order.

19
HTML

20
Sending Checkout API Requests to
Google
 In your development environment:
[Link] ID]]/checkoutFor
m
 In your production system:
 [Link] 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 ite
m.
 item_quantity_# - The parameter value identifies how many units of a particu
lar 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 pr
ice. The default value is USD (U.S. dollars).

 Shipping Parameters…

 Tax Parameters…

22
<form method="POST"
action="[Link]
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="item_name_2" value="Grape Jelly"/>

<input type="hidden" name="item_description_2" value="16 oz. bottle of Concord grape jelly."/>
<input type="hidden" name="item_quantity_2" value="1"/>
<input type="hidden" 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="[Link]
&w=180&h=46&style=white&variant=text&loc=en_US" height="46" width="180"/>

</form>

23
Viewing Order Statuses in the Merc
hant 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 ite
ms in your customer's shopping cart

 The XML will also contain information about the shipping options that the custom
er 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 valu
e in the form that contains the Google Checkout button

29
Integration (cont)
 In your development environment:

 <form method="POST"
action="[Link]
t">
 In your production system:

 <form method="POST"
action="[Link]

30
Google Checkout Buttons

31
32
When the customer clicks the Goog
le Checkout button
 Two methods to send information about the customer's order to Goo
gle 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 con
taining information about the customer's order as well as information about your s
hipping options and tax policies. You will then encode the XML document and em
bed 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 th
en post the XML to Google using an HTTP POST request. Google will then respo
nd to your request with a Google Checkout URL where your customer can compl
ete 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 Leve
l 1 Checkout integration.

 At this integration level, you will receive new order notifications via e
mail. You can then manage orders using the Merchant Center, a Go
ogle 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 su
bmitted through Google Checkout or to send updates for existing orders. As
such, the Notification API allows merchants to modify their systems to auto
matically receive order information from Google Checkout.

 The Order Processing API provides functions that let merchants change a
n order's status or add information to an order. Thus, the Order Processing
API lets merchants modify their systems to automatically update Google Ch
eckout orders.

 To implement these APIs, you must create a web service that sends and rec
eives XML messages about new orders and order status updates

36
Processing an Order
 (This process flow describes the first method, in which the order info
rmation is embedded in the form that displays the Google Checkout
button. When the customer clicks the Google Checkout button, the c
ustomer'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 inf
ormation 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 proc
ess.

 If you have completed a Level 1 integration, you will complete the se

cond set of steps through the Merchant Center. If you have complet
ed a Level 2 integration, you can modify your internal order processi
ng systems to handle these steps. You can also opt to use the Merc
hant 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 re
placed 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 req
uests. 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 elem
ent if you wanted to instruct Google Checkout to send an <authorizatio
n-amount-notification> after a customer submits a new order and Googl
e authorizes the customer's credit card.
 The Processing an Order and Submitting Server-to-Server Checkout API Re
quests sections of this document explain two different processes for creatin
g and submitting Checkout API requests.

41
Create an HMAC-SHA-1 signature
 You must create an HMAC-SHA-1 signature, a cryptographically se
cure value that enables Google to verify that the XML in the
<checkout-shopping-cart> structure was not altered before Google r
eceived it.

 Most development environments provide a function for creating HM

AC-SHA-1 signatures. To create the signature, call the appropriate f
unction, passing the <checkout-shopping-cart> XML structure and y
our Merchant Key as parameters to the function.

42
Base64-encode the cart
 After you create the signature, base64-encode the
<checkout-shopping-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 ste
p 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 C
heckout button.

45
46
Receive the new order notification
 When a customer submits an order, Google can notify you that the n
ew order has been submitted. There are two ways to receive new or
der notifications:

 Google can send email notifications for new orders. If you have not impl
emented the Notification API, Google will automatically email you to noti
fy 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 notific
ation will include the order shopping cart as well as other transaction det
ails such as the shipping method, shipping address and taxes for the or
der.

47
48
Add tracking information to the orde
r
 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 tr
acking 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 t
he Merchant Center and on the buyer's account page. There are tw
o 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 rem
ove 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 ar
chive 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 archive-o
rder command:

51
Typical Order Flow
 Figure 1: An order is placed by a customer, accepted by the mercha
nt and the customer is charged.

 Figure 2: The merchant processes the order, ships the order, and th
en archives the order after it has been delivered to the customer.

52
53
54
Credit Card Authorization and Capt
ure
 After a new order is confirmed by the buyer, Google will attempt to authorize the buye
r's credit card for the full order amount. If the authorization succeeds and the order pa
sses Google's risk checks, the order's financial order state will be updated to CHARG
EABLE. 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. Ho
wever, if the buyer does not supply a new credit card within 72 hours after the email i
s sent, Google will cancel the order.

 After payment has been authorized, you can charge the order for any amount up to th
e authorized amount. You can continue charging an order until all authorized funds h
ave been captured.

 Merchants can instruct Google Checkout to automatically charge orders as soon as t

hey become chargeable.

55
Authorizing Payment before Shippi
ng Items
 When a customer places an order, the new order will appear in your Inbox in your Merchant Cent
er 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 custom
er'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. Yo
u 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 c
ustomer, you would click the Charge button that appears next to the order in your Merchant Cent
er Inbox.

 Level 2 only: If you have implemented the Order Processing and Notification APIs, you should no
t 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
 [Link]
/checkout
 [Link]
t

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 t
he characters as hexadecimal numeric character references.
 The following table shows the numeric character references for these characters:You can use all other UTF-
8 characters directly.

 Google will not render HTML tags that you include in XML element values. If you pass HTML tag
s, such as in the <item-name> and <item-description> elements, Google will remove the HTML ta
gs and display the text without formatting.

 Unless otherwise noted, string elements in Google Checkout are not limited to any particular leng
th.

59
Internationalization
 Google Checkout includes the following internationalization-ready fe
atures:

 All XML messages between you and Google Checkout use UTF-8 (Unicode) enc
oding.

 Time/date values use the ISO 8601 standard, which specifies time as an offset fr
om UTC.


All money elements have a currency attribute.

60
Immediate (Synchronous) Respons
es to Posts
 When you post an API request to Google, Google Checkout evaluat
es your XML request to ensure that it is valid and returns a synchron
ous HTTP response to indicate whether your request is valid.

 A valid request must conform with the Google Checkout XML schem
a and must also request a legitimate action.

61
Immediate (Synchronous) Respons
es 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 C
heckout will return an <error> response to your request
 Invalid argument
 Invalid state change

62
Security Requirements and Precaut
ions
 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 y
our Merchant Key as the password. To obtain the header value for an order proc
essing request, take your Merchant ID and then append a colon (:) and your Mer
chant Key. Finally, base64-encode the entire value. Google uses the same proce
ss to create the authorization headers for notifications. As such, when you receiv
e 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=UTF-

8

 Include the Accept header with the value application/xml; charset=UTF-8

63
Security Requirements and Precaut
ions (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
 [Link]

XML API Developer's Guide

 [Link]

Thanks

65