1 Google Checkout API Jingsong Wang Arpril 2, 2007

2 Agenda Why How to use How to integrate

3 Agenda Why How to use How to integrate

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 <input type="image" name="Google Checkout" alt="Fast checkout through Google" src=" variant=text&loc=en_US" height="46" width="180"/>

8

9 Agenda Why How to use How to integrate

10 Sign In/Sign Up page

11 Place Order

12 Order Confirmation

13 Agenda Why How to use How to integrate

14 How to integrate HTML APIs XML APIs

15 How to integrate 1. Go to to set up test accounts in the Google Checkout Sandbox service.  Create your buyer account at  Create your merchant account at

16 How to integrate (cont) 2. Go to to sign up for a Google Checkout merchant accounthttp://checkout.google.com/sell/signup

17 How to integrate (cont) 3. Sign in to your test merchant account at to locate your Merchant ID and your Merchant Key.

18 How to integrate (cont) 4. Add a Google Checkout button to the checkout pages on your online store.

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

20 HTML

21 Sending Checkout API Requests to Google In your development environment: ID]]/checkoutForm In your production system:  ID]]/checkoutForm

22 Checkout API Query key strings  Item Parameters item_name_# * - The parameter value identifies the name of the item. item_name_# item_description_# * - The parameter value provides a description of the item. item_description_# item_quantity_# - The parameter value identifies how many units of a particular item are included in the customer's shopping cart. item_quantity_# item_price_#* - The parameter value identifies the price of the item. item_price_# item_currency_# - The parameter value identifies the currency for the item price. The default value is USD (U.S. dollars). item_currency_#  Shipping Parameters…  Tax Parameters…

23 <form method="POST" action=" accept-charset="utf-8"> <input type="image" name="Google Checkout" alt="Fast checkout through Google" src=" &w=180&h=46&style=white&variant=text&loc=en_US" height="46" width="180"/>

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

25

26

27

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:  In your production system: 

31 Google Checkout Buttons

32

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

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 Level 1 Checkout integration. At this integration level, you will receive new order notifications via . You can then manage orders using the Merchant Center, a Google application that lets you track orders from your web browser.Merchant Center

36 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

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.Merchant Center

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 element is the root tag for Checkout API requests. This tag contains three subtags.    optional 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 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.Processing an OrderSubmitting Server-to-Server 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 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 XML structure and your Merchant Key as parameters to the function.

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

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 Checkout button.

46

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 notifications for new orders. If you have not implemented the Notification API, Google will automatically 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.new-order-notification

48

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.add-tracking-data

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:  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.deliver-order

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:  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- order command:archive-orderarchive- order

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.

53

54

55 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 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 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 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.Merchant Center 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 notificationnew order notification  The risk information notificationrisk information notification  The order state change notification informing you that the order's financial-order-state has been updated to CHARGEABLEorder state change notification

57 Others.. Reauthorizing a Customer's Credit Card Buyer Refund Request

58 Posting XML Messages to Google /checkout

59 Guidelines for XML API Requests Specify UTF-8 encoding by including the following line at the start of each XML API request:  To include the XML reserved characters &, 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 and 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 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.

62 Immediate (Synchronous) Responses to Posts (cont..) If your request is valid, Google will return a response. If your request is not properly formed or requests an invalid status change, Google Checkout will return an 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  Merchant Key is HsYXFoZfHAqyLcCRYeH8qQ,  Base64-encode the value :HsYXFoZfHAqyLcCRYeH8qQ The base64-encoded value would appear in the request header:

65 Source HTML API Developer's Guide XML API Developer's Guide Thanks