1 Google Checkout API Jingsong Wang Arpril 2, 2007.

1

Google Checkout API

Jingsong Wang

Arpril 2, 2007

2

Agenda

Why How to use How to integrate

3

Agenda


4

Why Google Checkout

Sell more.

Spend less.

Grow your business.

5

Why Google Checkout (cont..)

Customers, You

Google Checkout is a fast, convenient checkout process that complements your existing process

until 2008, FREE..

6

Benefits

Attract more leads.

Convert more leads into sales.

Process sales for free.

Protect yourself from fraud.

7

Example<form method="POST" action="https://sandbox.google.com/checkout/cws/v2/Merchant/1234567890/checkoutForm" 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="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>

9

Agenda


10

Sign In/Sign Up page

11

Place Order

12

Order Confirmation

13

Agenda


14

How to integrate

HTML APIs

XML APIs

15

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/.

16

How to integrate (cont)

2. Go to http://checkout.google.com/sell/signup to sign up for a Google Checkout merchant account

17


3. Sign in to your test merchant account at https://sandbox.google.com/checkout/sell to locate your Merchant ID and

your Merchant Key.

18


4. Add a Google Checkout button to the checkout pages on your online store.

19


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.

20

HTML

21

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

22

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…

23

<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="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="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>

24

Viewing Order Statuses in the Merchant Center financial-order-state

fulfillment-order-state

28

XML

29

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

30

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">

31

Google Checkout Buttons

33

When the customer clicks the Google 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 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.

34

Integration Options

Level 1 Integration - Shopping Cart Integration

Level 2 Integration - Order Processing Integration

35

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 email. You can then manage orders using the Merchant Center, a Google application that lets you track orders from your web browser.

36

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

37

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. )

38

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.

39

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.

40

Create a checkout shopping cart

41

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.

42

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 y

our Merchant Key as parameters to the function.

43

Base64-encode the cart

After you create the signature, base64-encode the <checkout-shopping-cart> XML structure

44

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.

45

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.

47

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.

49

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.

50

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:


Level 2 only: If you have implemented the Order Processing API, you can send a deliver-order command to Google.

51

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:


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-order command:

52

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.

55

Credit Card Authorization and Capture 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 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.

56

Authorizing Payment before Shipping 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 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

57

Others..

Reauthorizing a Customer's Credit Card Buyer Refund Request

58

Posting XML Messages to Google

https://sandbox.google.com/checkout/cws/v2/Merchant/1234567890/checkout

https://checkout.google.com/cws/v2/Merchant/1234567890/checkout

59

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 UTF-8 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.

60

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.

61

Immediate (Synchronous) Responses 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 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.

62

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

63

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=UTF-8

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

64

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:

65

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

1 Google Checkout API Jingsong Wang Arpril 2, 2007.

Documents

Transcript of 1 Google Checkout API Jingsong Wang Arpril 2, 2007.