|
このページは大阪弁化フィルタによって翻訳生成されたんですわ。 |
Google Checkout lets your customers buy items from you quickly and securely using a Google username and password. You can use Google Checkout to charge customers' credit cards, track orders through your fulfillment process and receive order payments in your bank account. As such, Google Checkout touches each step of the customer's shopping experience, beginning with the customer's search for an item and continuing through the order checkout and fulfillment processes.
Google Checkout also works with AdWords, Google's search advertising program, to increase your sales and minimize your expenses. A Google Checkout badge will display next to your AdWords ads, helping shoppers notice your ads in their search results. In addition, for every dollar you spend on AdWords, you can process $10 worth of sales for free.
Merchants can choose between two types of Google Checkout implementation options:
XML APIs enable merchants to access all Google Checkout features. XML implementations are recommended for merchants who need to be able to digitally sign orders before sending them to Google. XML implementations are also recommended for merchants who want to offer coupons or discounts and for merchants who plan to integrate Google Checkout with their internal order processing and billing systems.
HTML APIs enable merchants to send information to Google Checkout and receive information from Google Checkout using name/value pairs in HTML forms rather than XML. Merchants can also use the HTML API to submit name=value pairs via a server-to-server HTTP POST request. HTML implementations are particularly recommended for small merchants who do not want to generate XML. Merchants can not digitally sign orders in HTML implementations, so merchants who use this implementation and do not submit server-to-server requests should plan to review orders manually.
This document provides an overview of the Google Checkout XML API and explains the basics of how to integrate your website with Google Checkout. Many sections of this document, in turn, link to additional documentation that explains a specific Checkout feature or aspect of the XML API in greater detail.
This document contains the following sections:
The Buyer Experience section explains how customers complete orders using Google Checkout and provides screenshots of the Google Checkout user interface for buyers.
The Getting Started with Google Checkout section explains how to sign up with Google Checkout. This section also explains how to create Google Checkout buttons that your customers can click on to begin the checkout process.
The Technical Overview explains the different components of the Google Checkout XML API and discusses different Checkout integration options. This section also contains a technical discussion that explains how you convey order information to Google and then manage and process Google Checkout orders. Finally, this section describes Google's policy for authorizing and charging customers' credit cards.
The API Reference section explains how to submit API requests to Google and also explains the responses that Google sends to an API request. This section also describes a Google Checkout diagnostic feature that lets you verify that an API request contains valid XML. Finally, this section explains how to use HTTP Basic Authentication to send certain types of API requests.
The Checkout API, Merchant Calculations API, Notification API and Order Processing API sections provide specific details about the different Google Checkout APIs. Each of these sections links to one or more additional documents that contain instructions for implementing specific API features.
The Using the Google Checkout Merchant Center section describes Google's online interface for managing orders.
The Testing and QA section discusses different resources that can help you to test your Google Checkout integration, including credit card test cases that allow you to submit test orders that will return a specific type of Address Verification System (AVS) response or credit verification value.
Note: The Google Checkout XML API Tag Reference defines all of the XML elements in the Google Checkout XML schema. In addition, documents that explain individual Checkout features also contain the list of XML element definitions that pertain to those features. For example, the document that explains how to implement flat-rate shipping methods contains the definitions for XML tags used to describe those shipping methods.
This section describes your customer's experience in completing an order with Google Checkout. During this process, the buyer progresses through four different pages beginning with a page on your site that displays a Google Checkout button and culminating with the Google Checkout Order Confirmation page.
The following steps explain the user experience on these pages.
The Google Checkout order process begins when the customer shops on your site and adds items to a virtual shopping cart. In addition to your regular checkout options, your web pages will display a Google Checkout button. This button will be contained within a form on your page.
When the customer clicks the Google Checkout button, the customer's browser will submit the shopping cart information to Google. You can include the customer's order information in an HTML form on your page or submit the order information using a server-to-server HTTP POST request. Google Checkout will then display the Sign In/Sign Up page, which shows the items in the customer's order and the shipping options available for the order. The Sign In/Sign Up page, which is shown below, also allows the customer to create a new Google Account or log in to an existing account.
If Google detects a cookie indicating that the customer already has a Google Account and the account already contains credit card information, the right side of this page will display the email address for that account. In this case, the customer will only need to enter the password for that account. If the customer has recently shopped with Google Checkout and has a valid cookie, the Sign In/Sign Up page may not appear at all, in which case the customer will proceed directly to the Place Order page. The interface will also change slightly for customers who have a Google Account but do not have a credit card associated with their account.
After the customer creates a new Google Account or signs in to an existing account, Google will display the Place Order page. This page, which is shown below, lists the items in the customer's order and the shipping options available for the order. The Place Order page also lets the customer choose the shipping address for the order and the credit card to charge for the order. In addition, the Place Order page allows the customer to choose whether to share her email address with the merchant or receive promotional email from the merchant. Finally, the Place Order page displays Google's billing policy and can also display information about your return policy.
User Interface Elements under Your Control
The following image highlights the elements on the Place Order page that display values that you include in order information that you send to Google. The numbered list that follows the image explains how these elements correspond to the information in a Checkout API request. These API elements are also discussed in further detail in the Checkout API section of this document.
The following list explains the numbered elements shown in the image.
The target URL for the Change order link is the value of the <edit-cart-url> tag.
The Qty column displays the value of the <quantity> tag for each item in the order.
The bold text in the Item column displays the value of the <item-name> tag for each item in the order.
The text following the name of each item is the <item-description> for that item.
The Price column displays the value of the <unit-price> tag for each item in the order as well as the appropriate currency symbol for that price.
The pulldown menu in the Shipping & Handling row displays a list of the shipping methods that you offer, which are contained in the <shipping-methods> tag in your API request. Each item in the pulldown menu displays the name and price of the shipping method.
The Enter coupon or gift card ... link displays if either the <accept-gift-certificates> or <accept-merchant-coupons> element has a value of true in the Checkout API request.
The Tax row displays the total calculated tax for the order based on the information included in the <tax-tables> that you send to Google with each order. The state abbreviation (NY) next to the word Tax identifies the state of the shipping address selected by the buyer.
Email Address Sharing and Forwarding
When a transaction occurs, Google always provides you with an email address to contact the buyer. You can send correspondence to the buyer's email address for order processing issues and, if the buyer consented to receive promotional email, for marketing purposes (see Google Checkout Program Policies and Guidelines, section 1).
As shown in the screenshot of the Place Order page shown above, Google does offer buyers the option of keeping their email address confidential. Depending on the buyer's preferences, Google will send you either the email address that the buyer used to register with Google or an email address that forwards through Google to the buyer's registered email address. If the buyer prefers to forward email through Google and decides that he or she no longer wants to receive email from a specific merchant, the buyer can deactivate email forwarding from a specific merchant at any time.
Google Checkout's email forwarding feature helps increase the effectiveness of email marketing in several ways. First, the feature gives buyers the confidence to consent to receive marketing emails, even from unfamiliar merchants. With email forwarding, the merchant sends promotional emails to a Google-maintained email address, and Google forwards the email on to the buyer. The buyer can always opt to turn off email forwarding from that merchant if the promotional emails are no longer desired. This feature may also give trusted merchants access to the buyer's primary email mailbox for marketing. Whereas many buyers provide merchants with a separate junk email address for promotional mail, Google Checkout is more likely to forward emails directly to customers' primary email accounts. This system allows Checkout merchants to have greater access to the email accounts that buyers regularly read and use.
When the customer clicks the Place your order now button on the Place Order page, Google starts to process the order and displays the Order Confirmation page. This page thanks the customer for completing the order and also displays a link to your site so the customer can continue shopping.
This section explains how to become a Google Checkout merchant and begin to integrate your online store.
Go to http://sandbox.google.com/checkout/sell/ to set up test accounts in the Google Checkout Sandbox service. The Sandbox is a development environment that is designed to help you test your Google Checkout implementation. The Sandbox offers the same functionality as the production Google Checkout system with the following exceptions:
You need to create two test accounts in the Sandbox. One of these accounts will function as a buyer account and the other will function as your merchant account. Please note that Google Checkout will not let you use your merchant account to complete an order at your own store. (In other words, the same account can not function as both the customer and the merchant for the same transaction.) In addition, you need to provide different information to create these two accounts.
The following guidelines explain how to set up your test accounts:
Skip any sections that ask for your bank account information. Since the Sandbox system does not process billing or payments, this information is not necessary when you are testing your implementation.
Enter any name and address as long as the State field contains a valid two-letter abbreviation for a U.S. state and the Zip Code field contains a five-digit or nine-digit zip code. (You do not need to enter the correct zip code for the address.)
Enter any 10-digit phone number for the Phone Number field.
Enter any value in either the Federal tax ID or Social Security number fields.
Use one of the credit card numbers in the following table:
| Card Type | Card Number | CVC | Expiration Date |
| American Express | 3782 8224 6310 005 | any four digits | any future date |
| Discover | 6011 1111 1111 1117 | any three digits | any future date |
| MasterCard | 5555 5555 5555 4444 | any three digits | any future date |
| VISA | 4111 1111 1111 1111 | any three digits | any future date |
Note: Merchants in the United Kingdom should not use an American Express card.
Go to http://checkout.google.com/sell/signup to sign up for a Google Checkout merchant account. Complete the sign-up process and provide valid values for all fields. You will need the federal tax ID number for your business or a credit card and your Social Security number.
Please note that you will use this account for your production service whereas the accounts you created in the previous step are for testing your Checkout integration.
Sign in to the accounts that you created in steps 1 and 2 to locate the Merchant ID and Merchant Key for each account. You will need these values to create Google Checkout buttons and to send API requests to Google Checkout. After signing in to each account, click on the Settings tab. Then click on the Integration link on the left side of the page. Your 10- or 15-digit Merchant ID and your Merchant Key will both be listed under the Account information header.
You should never share your Merchant Key with anyone. Google uses your Merchant Key to authenticate your API requests, and no Google representative will ever ask you for your Merchant Key.
This step is optional. You can use curl (or a similar tool) to verify that your server communicates properly with Google Checkout. To complete this test, enter the following commands on one line each in your terminal window. Replace the MERCHANT_ID and MERCHANT_KEY strings with the Merchant ID and Merchant Key for your Sandbox account. Replace the same strings in command 2 with the Merchant ID and Merchant Key for your Google Checkout merchant account.
Command 1: curl -d '<hello xmlns="http://checkout.google.com/schema/2"/>' https://MERCHANT_ID:MERCHANT_KEY@sandbox.google.com/checkout/api/checkout/v2/request/Merchant/MERCHANT_ID Command 2: curl -d '<hello xmlns="http://checkout.google.com/schema/2"/>' https://MERCHANT_ID:MERCHANT_KEY@checkout.google.com/api/checkout/v2/request/Merchant/MERCHANT_ID
Google Checkout will respond to each command with the <bye> response. If you do not receive this type of response, then Google Checkout did not properly process your request. For example, if you receive an error response, that response should specify the reason that your request failed. If you do not receive a response at all, then your server may be unable to communicate with Google Checkout. The following XML excerpt shows a sample <bye> response:
<?xml version="1.0" encoding="UTF-8"?> <bye xmlns="http://checkout.google.com/schema/2" serial-number="c567262a-dd13-4084-b8d3-6ccfbbc69d03" />
Add a Google Checkout button to the checkout pages on your online store. The button needs to be embedded in a form in the HTML for your pages. The button should appear next to your existing checkout buttons. Note: You may add more than one Google Checkout button to your page.
Modify the code for your online store so that the form containing the Google Checkout button also submits information about your customer's order.
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.
The Checkout API section provides instructions for creating the shopping cart XML. In addition, the Sending Order Information to Google Checkout section explains how to encrypt your XML document and include it in the form on your checkout page.
In your development environment, your form needs to submit orders to the following URL. You must replace the text MERCHANT_ID with the Merchant ID from your Sandbox account.
Note: Your production account will have a different Merchant ID and Merchant Key than your Sandbox account. Your code should use the values from the Sandbox account when communicating with the Google Checkout Sandbox service. Similarly, your code should use the values from your production account when communicating with the Google Checkout production service.
Your production system will submit orders to the following URL. You must replace the text MERCHANT_ID with the Merchant ID from your production account.
This step is optional. Set up a web service to perform custom calculations for tax, shipping, coupons and gift certificates after the customer has reviewed the order in Google Checkout. The Merchant Calculations API section provides detailed information about custom calculations.
This step is optional. Create a web service that receives and processes new order notifications from Google Checkout. The Notification API and Order Processing API sections explain the ways that you can integrate your internal order processing systems with Google Checkout.
To ensure a positive, consistent buying experience for your customers, please ensure that your site complies with the Google Checkout API integration checklist. The checklist provides guidelines for Google Checkout button placement, the checkout order flow and branding.
After you have thoroughly tested your Google Checkout implementation with the Sandbox service, release your code to your production system to begin accepting orders through Google Checkout. Please remember that you must use a different Merchant ID and Merchant Key in your production environment than you use in your test environment. Your Google Checkout buttons will also have different URLs in your test and production environments. You will receive an error if you try to process orders using the wrong Merchant ID or Merchant Key.
The Google Checkout Program Policies and Guidelines (section 4b) state that you must place a Google Checkout button immediately beside, above or below every existing checkout button or link on your website.
Google hosts the image for the Google Checkout buttons that you place on your pages. The base URL for the image is http://checkout.google.com/buttons/checkout.gif. When displaying images in your development environment, request the image http://sandbox.google.com/checkout/buttons/checkout.gif.
To display an image, you must add several parameters to the base URL as name=value pairs. The following table lists the parameters that you need to add to the Google Checkout button image. All parameters are required unless otherwise noted.
| Parameter | Description |
|---|---|
| merchant_id | This parameter identifies your Merchant ID. Note: You need to use different Merchant IDs for buttons in your test and production environments. Please see the Getting Started with Google Checkout section for more details. |
| w | This parameter specifies the width of the button in pixels. You must use one of the sizes in the following list. Valid values for the w parameter are shown in bold text.
|
| h | This parameter specifies the height of the button in pixels. You must use one of the sizes in the following list. Valid values for the h parameter are shown in bold text.
|
| style | This parameter specifies the background color for the button. Use the parameter value white to indicate that you are placing the button on a white background and the value trans to indicate that you are placing the button on a colored background. |
| variant | This value indicates whether the button is clickable or disabled. Use the parameter value text to indicate that the button is clickable and the value disabled to indicate that the button is disabled. You should only display a disabled button if the Google Checkout option is not available for a particular order. Please see the Google Checkout Content policies for details about the types of items that may not be sold through Google Checkout. |
| loc | Optional. This parameter identifies a locale associated with the transaction.
|
For example, the following form contains a large Google Checkout button on a white background. The <input> tag for the button is shown in bold text.
<form method="POST"
action="https://sandbox.google.com/checkout/api/checkout/v2/checkout/Merchant/1234567890">
<input type="hidden" name="cart"
value="PD94bWwgdmVyc2lvbj0iMS4wIj8+CjxjaGVja291dC1zaG9wcGlu">
<input type="hidden" name="signature"
value="kdjsf590GFDGK23l2kgit259fjSDKET0592jalkfwe3539Gjekwu">
<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>
The button in the form displays the following image:
Note: You can also use the Checkout Button URL Generator to quickly create the URLs for the Checkout buttons that will display on your site.
Google Analytics enables a merchant to understand how visitors interact with the merchant's website. Google Analytics also helps the merchant identify navigational components that promote or inhibit conversions to sales, enabling the merchant to optimize ad campaigns and website content for increased sales.
Google Checkout merchants can use Google Analytics to track buyers who leave their sites to complete the checkout process using Google Checkout. Please see the Using Google Analytics with Google Checkout document for instructions on how to track Google Checkout orders using Google Analytics.
Google provides Buy Now buttons as a simple way to offer single items for sale through Google Checkout. If you use Buy Now buttons, you do not need to implement the Checkout API as described in this document. The Buy Now button will contain all of the shopping cart information that you need to send to Google for that item.
To create Buy Now buttons, go to the Merchant Center, click the Settings tab and then click the Buy Now buttons link. After you generate the button, copy the code for the button and then paste that code in an appropriate location on your website. For more information about Buy Now buttons, see the Google Checkout Merchant FAQ.
Note: You can not specify tax and shipping rates using Buy Now buttons. However, you can include taxes and shipping charges in the cost of the item.
Google provides a suite a four APIs that enable you to integrate your website with Google Checkout. Please note that you must at least implement the Checkout API to integrate with Google Checkout; the remaining APIs are optional.
The Checkout API allows you to send Google the list of items in your customer's shopping cart. Checkout API requests also contain additional information that is used during the checkout process, such as tax tables and a list of the shipping options that you offer.
The Merchant Calculations API enables you to use your own business logic to compute order totals using information that is not known when you post a Checkout API request. To implement this API, you must create a web service that calculates these values.
This API lets you compute taxes, shipping costs, and price adjustments for coupons or gift certificates. You can choose to calculate any or all of these values. For example, if you have stores or offices in one state and charge the same tax rate for all of your items, you may not need to use this API. However, if your method of computing shipping costs considers the ship-from address and the ship-to address, then you would need to use this API so that you could calculate shipping costs after the buyer selected a shipping address.
The Notification API lets you integrate Google Checkout with your internal order processing systems by allowing those systems to automatically receive order information from Google. Google sends notifications to inform you of new orders or to send updates for existing orders. To implement this API, you must create a web service that receives notifications from Google and then relays the information in those requests to your internal systems.
The Order Processing API lets you integrate Google Checkout with your internal order processing systems by allowing those systems to automatically send updated order information to Google. The Order Processing API enables you to automatically update an order's financial state or its fulfillment state. For example, you can use this API to relay shipment tracking information for an order or to instruct Google to charge a customer for an order.
As noted above, you must implement the Checkout API to integrate with Google Checkout. You can also choose to implement the Merchant Calculations API, which allows you to compute certain values after the buyer links to Google Checkout to complete an order.
Once you have implemented the Checkout API, Google will send you an email notification when a customer completes an order. You can also use the Google Checkout Merchant Center, an online interface where you can manage orders placed through Google Checkout, to charge customers, add shipment tracking information and perform other order processing tasks.
Note: If you choose to only implement the Checkout API, and you decide not to complete an Order Processing integration, Google recommends that you consider implementing the HTML API rather than the XML API.
After completing your shopping cart integration, you also have the option of implementing the Notification and Order Processing APIs to further integrate Google Checkout with your website and internal order processing systems. Typically, merchants that integrate the Notification API and the Order Processing API will implement both APIs at the same time.
When your customer clicks a Google Checkout button to begin the checkout process, your site will send a Checkout API request containing information about the customer's shopping cart. The Checkout API request is an XML document that provides details about the items in the customer's order. The request also contains additional information that is required to complete the order, such as tax rates and a list of available shipping options.
The following XML sample shows a very simple order. This request defines a shopping cart that contains one item and offers one shipping option. This example does not specify tax information. Please see the Checkout API section and the additional documentation explaining shipping methods and tax tables for additional XML examples.
<?xml version="1.0" encoding="UTF-8"?> <checkout-shopping-cart xmlns="http://checkout.google.com/schema/2"> <shopping-cart> <items> <item> <item-name>HelloWorld 2GB MP3 Player</item-name> <item-description>HelloWorld, the simple MP3 player</item-description> <unit-price currency="USD">159.99</unit-price> <quantity>1</quantity> </item> </items> </shopping-cart> <checkout-flow-support> <merchant-checkout-flow-support> <shipping-methods> <flat-rate-shipping name="SuperShip Ground"> <price currency="USD">9.99</price> </flat-rate-shipping> </shipping-methods> </merchant-checkout-flow-support> </checkout-flow-support> </checkout-shopping-cart>
You can use either of the two methods described below to send Checkout API requests to Google so that your customer can complete an order. The Google Checkout Sample Code page provides ASP, Java, .NET, PHP and Perl code samples to help you with your integration.
Please note that your Checkout integration must allow the buyer to use the browser's Back button during the Google Checkout process, which is a requirement of the Google Checkout program (see Google Checkout Program Policies and Guidelines, section 4e).
Option A - Configure your form to submit directly to Google Checkout
This option explains how to embed your Checkout API request in the HTML form on your page that displays the Google Checkout button. When the buyer clicks the button, the form's action will send the Checkout API request (and the buyer) directly to Google Checkout. To keep the Checkout API request up to date, you must recreate its XML every time the buyer adds or removes an item.
Create an HMAC-SHA-1 signature, a cryptographically secure value that enables Google to verify that the your Checkout API request was not altered before Google received it. To create the signature, call the appropriate function in your development environment, passing the Checkout API XML structure and your Merchant Key as parameters to the function. (You can find your Merchant Key by signing into your Google Checkout account, clicking on the Settings tab and then clicking on the Integration link on the left side of the page.)
Note: When you call the function that generates the HMAC-SHA-1 signature, specify that you want the result in binary format. (Otherwise, the function may return a result in hexadecimal format.)
Base64-encode the Checkout API XML request. Most development environments provide a function for base64-encoding.
Using the same function as in the previous step, base64-encode the HMAC-SHA-1 signature that you created in step i.
Include the base64-encoded Checkout API request and the base64-encoded HMAC-SHA-1 signature in the form on your page that displays a Google Checkout button. The HTML example below shows a sample Google Checkout button form. The form contains two hidden input fields. The first field, which is assigned the name cart contains the base64-encoded Checkout API XML request. The second field, which is assigned the name signature, contains the base64-encoded HMAC-SHA-1 signature.
<form method="POST"
action="https://sandbox.google.com/checkout/api/checkout/v2/checkout/Merchant/1234567890">
<input type="hidden" name="cart"
value="PD94bWwgdmVyc2lvbj0iMS4wIj8+CjxjaGVja291dC1zaG9wcGlu">
<input type="hidden" name="signature"
value="kdjsf590GFDGK23l2kgit259fjSDKET0592jalkfwe3539Gjekwu">
<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>
The following diagram illustrates the actions performed in steps i through iv:
Option B - Submit a Server-to-Server Checkout API Request
When you submit a server-to-server Checkout API request, the form on your page that displays the Google Checkout button will submit to a web service running on your site. That service will then create the Checkout API XML request so that the request contains information about your customer's order. Your application will then send the Checkout API request to Google using HTTP POST. In response, Google will return a Google Checkout URL where your customer can complete the order, and you will redirect the customer to that URL.
The following list explains the basic steps for submitting server-to-server requests:
Write an application that creates a Checkout API XML request containing information about the customer's order.
Configure the forms on your site that display Google Checkout buttons to submit to a URL on your site that runs the application created in step i. When the buyer clicks a Google Checkout button, you will receive an HTTP POST request at that URL. Your application should then build a Checkout API request for the customer's order.
Send the XML to Google using an HTTP POST request. Please select the appropriate URL for your request from the list below.
If the request originates from your development environment, send it to the following URL. You must replace the string MERCHANT_ID with the Merchant ID for your Sandbox merchant account.
https://sandbox.google.com/checkout/api/checkout/v2/merchantCheckout/Merchant/MERCHANT_ID
If the request originates from your production environment, send it to the following URL. You must replace the string MERCHANT_ID with the Merchant ID for your production account.
https://checkout.google.com/api/checkout/v2/merchantCheckout/Merchant/MERCHANT_ID
If your request contains valid XML, Google will return a <checkout-redirect> response. This message identifies the Google Checkout URL where the customer can complete the order. The following XML shows a sample <checkout-redirect> response.
<?xml version="1.0" encoding="UTF-8"?> <checkout-redirect xmlns="http://checkout.google.com/schema/2" serial-number="981283ea-c324-44bb-a10c-fc3b2eba5707"> <redirect-url>https://checkout.google.com/buy&8572098456</redirect-url> </checkout-redirect>
Note: The URL may include an ampersand (&) character, encoded as & in the XML. Your XML processor should properly decode this character so that the URL to which you redirect the customer contains only the text "&" and not "&".
Send an HTTP 302 response to the HTTP POST request that you received when the customer clicked the Google Checkout button. The response needs to redirect the customer to the XML-decoded URL that you received in step 4.
Receiving new order notifications
When a customer completes an order, Google will notify you that the new order has been submitted using one, or both, of the following mechanisms:
Google automatically sends email notifications for new orders to all merchants who have not implemented the Notification API.
If you have implemented the Notification API, Google will send a new-order-notification to inform you of the new order. The notification will list the items in the order as well as other transaction details like the shipping method, shipping address and taxes for the order.
Even if you implement the Notification API, you can still receive email notifications by setting a preference in your Merchant Center account. To set this preference, log in to your account and click the Settings tab. Then click the Preferences link on the left side of the page and check the preference that says, "Email my customer support contact each time I receive an order, cancellation or other transaction."
Charging orders
After a customer submits an order, Google performs a risk assessment in an effort to avoid fraudulent charges. Google also authorizes the customer's credit card to ensure that it can be charged for the full amount of the order. There are several ways to charge a customer for an order.
You can click the Charge button next to the order in the Merchant Center.
You can instruct Google to automatically charge orders as soon as they become chargeable. The Credit Card Authorization and Capture section explains how to set this preference in your Google Checkout account.
If you have implemented the Notification and Order Processing APIs, your internal order processing systems can notify Google when an order should be charged. After the order is submitted, Google sends a new-order-notification, a risk-information-notification, and an order-state-change-notification to notify you of the order and to inform you when the order becomes chargeable. Each notification will specify the unique order number that Google assigned to the order.
At this point, you can send a charge-order command to tell Google to capture funds for the order. This command, which is part of the Order Processing API, uses the unique Google order number to identify the order to be charged.
After charging the order, Google will send you a charge-amount-notification to confirm that the charge was successfully executed.
When you charge an order, Google will update the buyer's purchase history page to indicate that the charge was executed. Other order status changes that you initiate through either the Merchant Center or through Order Processing API commands may also be reflected on the buyer's purchase history page.
Adding shipment tracking information
After shipping the order, you can add shipment tracking information that will appear on the buyer's account page. There are two ways to add shipment tracking information to an order:
Log in to your Merchant Center account and click on the order for which you want to add shipment tracking data. In the Shipping Information section of the page, select a carrier and enter a tracking number for the order shipment. Then click the Save button.
If you have implemented the Order Processing API, your internal systems can automatically send shipment tracking information directly to Google Checkout. Line-item shipping commands let you specify shipment tracking information on an item-by-item basis. You can also identify individual items in an order that are out-of-stock as well as items that have been canceled from an order or returned by the customer.
Marking orders as shipped
After you ship an order, you can log in to your Merchant Center account and click the Ship button next to the order. This action will mark the order as Shipped in the Merchant Center and on the buyer's account page.
If you have implemented the Order Processing API's line-item shipping commands, Google will automatically mark an order as shipped after you have sent API requests indicating that each item in the order has been shipped.
Archiving orders
After an order has been delivered, you can archive the order to remove it from the list of active orders that appears in the Merchant Center. (This step is optional; you do not need to archive orders.) There are two ways to archive an order:
Log in to your Merchant Center account and click the Archive button for the order.
If you have implemented the Order Processing API, you can send an archive-order command to Google.
This section illustrates the typical flow for a Google Checkout order. The order flow begins when the buyer clicks a Google Checkout button and ends when the buyer's order is delivered and the merchant archives the order. The diagram below is followed by a list of the order processing steps shown in the diagram. The list explains how each step is completed if you are using either the Merchant Center or the Notification and Order Processing APIs.
In the diagram, the green bar represents the merchant and the blue bar represents Google Checkout. The arrows between the bars identify the type of information that is being communicated during different stages of the order flow. All of these order updates are reflected in the Merchant Center. In addition, Google Checkout may send some types of information, such as new order notifications, via email. For merchants that have implemented an order processing integration, which includes implementation of the Notification and Order Processing APIs, arrows also represent messages that are exchanged between Google and the merchant.
There are also numerous alternate order flows. For example, the order illustrated in the diagram does not use the Merchant Calculations API. As such, one alternate order flow involves the merchant calculating taxes and shipping charges for an order after sending the order information to Google Checkout. Other alternate order flows include a failed credit card authorization or a need to cancel an order and refund the customer. Please see the Alternate Order Flow Diagrams document for more information about other common order flows.
Typical flow for Google Checkout orders:
Placing an Order
Your customer selects items and clicks the Google Checkout button on your site, sending the order information to Google Checkout.
Accepting an Order
The order appears in your Merchant Center inbox with a status of NEW. Google sends you an email to notify you of the order. If you have completed an order processing integration, Google sends a new order notification to inform your internal systems of the order. (You may not receive an email notification if you implemented the Notification API.)
Google conducts a risk assessment of the order to ensure that the customer is making a valid credit card purchase. The order status in the Merchant Center updates to REVIEWING. After Google completes its risk assessment, the Merchant Center will indicate whether the order is eligible for Google's Payment Guarantee Policy. If you have completed an order processing integration, Google also sends a risk information notification to inform your internal systems of the risk associated with the order.
Google authorizes the customer's credit card to be charged for the order. The Merchant Center inbox reflects this action by allowing you to charge the customer. If you have completed an order processing integration, Google also sends an order state change notification to inform your internal systems that the order is chargeable.
Charging an Order
You charge the customer for the order. You can charge the customer by clicking the Charge button next to the order in the Merchant Center. If you have completed an order processing integration, you can also send a charge-order request to Google Checkout.
Google begins charging the customer. In the Merchant Center, the Charge button will update so that it is not clickable. The order status will also update to Charging. You cannot execute any actions on an order while it is being charged. If you have completed an order processing integration, Google also sends an order state change notification to inform your internal systems that the order is being charged.
Google completes the charge. In the Merchant Center, the order history updates to indicate that the customer has been charged and reflects the amount of the charge. If you have completed an order processing integration, Google sends two notifications about the charge. First, it sends an order state change notification to inform your internal systems that the customer has been charged. It also sends a charge amount notification to inform your internal systems of the amount of the charge.
Shipping an Order
You ship the order to the customer. In the Merchant Center, you can click the Ship button that displays next to the order to update the order's fulfillment status to DELIVERED. You can also click on the order and enter shipment tracking information. If you enter shipment tracking information, Google will update the customer's account so that the customer can track the order shipment.
If you have completed an order processing integration, you can use Order Processing API commands to notify Google that the items in the order have been shipped and to provide shipment tracking information. After you have indicated that all of the items in the order have shipped, Google will update the order's fulfillment status to DELIVERED. At that point, Google will send an order state change notification confirming the status change.
After the order has been delivered, you can archive the order in the Merchant Center by clicking the Archive this Order button, as shown in the following image. When you archive an order, the order will display in your list of archived orders in the Merchant Center rather than in the inbox. If you have completed an order processing integration, you can also send an archive-order request to Google.
After a buyer confirms a new order, 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. At that time, 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. However, please note that there are two reasons that an authorization will become invalid:
Google Checkout credit card authorizations expire exactly seven days – 168 hours – after the time they are issued.
When you partially charge an order, the order's initial authorization becomes invalid even if its seven-day window has not expired. As such, any time an order has been partially charged, additional charges for the same order will not be authorized unless you request an explicit reauthorization.
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.
Note: If an order's initial authorization becomes invalid, and you have implemented the Notification API and the Order Processing API, you can explicitly reauthorize an order to verify that the credit card charge for the order will be successful. This feature allows you to wait until items are available before charging customers for those items, providing a better experience for customers who preorder items or order out-of-stock items. Explicit reauthorizations also benefit merchants that have a policy of shipping an item before charging the customer for that item. By explicitly reauthorizing the customer's credit card, the merchant can ship an order with confidence that the ensuing credit card charge will be successful. For more information about this feature, see the discussion of the <authorize-order> Order Processing API command.
Merchants can instruct Google Checkout to automatically charge orders as soon as they become chargeable. To activate this feature, log in to your Google Checkout account and click on the Settings tab. Then click the Preferences link in the menu on the left side of the page. Under the Order processing preferences header on the Preferences page, check the option for the auto-charging feature.
When a customer places an order, the new order will appear in your Merchant Center Inbox. Initially, the Merchant Center will display a status of Reviewing for the order. This status indicates that Google Checkout is trying to authorize the buyer's credit card for the amount of the purchase. As long as the order's status is Reviewing, you will not be able to charge the buyer.
After authorizing the buyer's credit card, Google will update the order's status from Reviewing to New. You should not ship 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, click the Charge button that appears next to the order in your Merchant Center Inbox.
If you have implemented the Notification API and the Order Processing API, you can also use the <charge-order> command to instruct Google to charge the buyer. Please note that if you have implemented the Notification API, you should not ship items unless you have received the following three notifications for the corresponding order:
Buyers can ask for a refund or cancellation by clicking the Questions about this order link on their order history page. If the buyer requests a refund, Google will send you an email to notify you of the request. Note that this email does not start the refund or cancellation process. The link merely enables the buyer to inform you that he would like to cancel an order or receive a refund for an order.
The following sections provide general details about the XML messages that you will exchange with Google Checkout. These sections discuss guidelines for posting XML messages to Google, ensuring the security of your transactions and handling Google's responses to your API requests.
When you sign up with Google Checkout, Google assigns you a unique identifier called a Merchant ID. The Getting Started with Google Checkout (step 3) explains how to locate this value. Your Merchant ID is included in the URLs to which you send Google Checkout API requests.
If you configure your Google Checkout button to submit directly to Google, you will send Checkout API requests to the following URLs. (Please note that these URLs are not used for server-to-server Checkout API requests.) The first URL is for requests from your test environment and the second URL is for requests from your production site. In the first URL, you must replace the MERCHANT_ID string with the Merchant ID for your Sandbox account. You must replace the same string in the second URL with the Merchant ID for your Google Checkout merchant account.
https://sandbox.google.com/checkout/api/checkout/v2/checkout/Merchant/MERCHANT_ID https://checkout.google.com/api/checkout/v2/checkout/Merchant/MERCHANT_ID
The following URLs are used for server-to-server Checkout API requests. Again, you must replace the MERCHANT_ID string with the appropriate value as described in the previous paragraph.
https://sandbox.google.com/checkout/api/checkout/v2/merchantCheckout/Merchant/MERCHANT_ID https://checkout.google.com/api/checkout/v2/merchantCheckout/Merchant/MERCHANT_ID
Finally, the following URLs are used for Order Processing API requests. Again, you must replace the MERCHANT_ID string with the appropriate value.
https://sandbox.google.com/checkout/api/checkout/v2/request/Merchant/MERCHANT_ID https://checkout.google.com/api/checkout/v2/request/Merchant/MERCHANT_ID
The following guidelines explain how to format XML documents that you send in Google Checkout API requests. Some of these guidelines apply specifically to XML elements that contain text strings, including URLs.
All XML messages between you and Google Checkout must use UTF-8 (Unicode) encoding. 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. Note: This guideline also applies to URL parameters that are included in XML values.
The following table shows the numeric character references for these characters:
| Character | Hexadecimal character reference |
| & | & |
| < | < |
| > | > |
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.
Time/date values use the ISO 8601 standard, which specifies time as an offset from UTC.
All money elements must have a currency attribute.
The following instructions explain how to format HTTP request headers to use HTTP Basic Authentication. You will need to follow these steps to send server-to-server requests to Google, including server-to-server Checkout API requests, Merchant Calculations API responses or Order Processing API requests.
Please note that Google also uses HTTP Basic Authentication to send Merchant Calculations API requests and Notification API requests to you. As such, when you receive a notification from Google, you can base64-decode the authorization header to confirm that the notification is valid.
Create a properly formatted XML file for the command being executed. The Google Checkout XML schema defines an XML structure for each type of API request.
Follow these steps to create the HTTPS header for your request:
Create the Authorization header for your request.
Append a colon to your Google Checkout Merchant ID. Then append your Google Checkout Merchant Key to this value. (The value has the format MERCHANT_ID:MERCHANT_KEY.)
Base64-encode the value you produced in the previous step.
Provide the Authorization header for your request using the following format. Replace the text Authorization_Key in this header with your authorization key:
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
For example, if your Merchant ID is 1234567890 and your Merchant Key is HsYXFoZfHAqyLcCRYeH8qQ, you would base64-encode the value 1234567890:HsYXFoZfHAqyLcCRYeH8qQ. The example below shows how the base64-encoded value would appear in your request header:
Post the XML structure created in step 1 to Google Checkout. This URL is constructed using your Google-assigned Merchant ID.
Note: You must replace the string MERCHANT_ID with your Google Checkout Merchant ID.
You must also secure Notification and Order Processing API requests with an SSL certificate. The Implementing the Notification API document and the Order Processing API section of this document provide more information about that requirement.
Google Checkout provides a diagnostic feature that lets you verify that Checkout and Order Processing API requests contain valid XML without actually submitting those requests. To use this feature, construct the XML for the API request and then submit it to Google Checkout's validator by appending /diagnose to the submission URL.
Use the following URLs to validate Checkout API requests that do not use the server-to-server posting method. You must replace the MERCHANT_ID string in each URL with your Merchant ID. The first URL will contain the Merchant ID for your Sandbox account; the second URL will contain the Merchant ID for your Google Checkout merchant account.
https://sandbox.google.com/checkout/api/checkout/v2/checkout/Merchant/MERCHANT_ID/diagnose https://checkout.google.com/api/checkout/v2/checkout/Merchant/MERCHANT_ID/diagnose
For server-to-server Checkout API requests, use the following URLs:
https://sandbox.google.com/checkout/api/checkout/v2/merchantCheckout/Merchant/MERCHANT_ID/diagnose https://checkout.google.com/api/checkout/v2/merchantCheckout/Merchant/MERCHANT_ID/diagnose
For Order Processing API commands, use the following URLs:
https://sandbox.google.com/checkout/api/checkout/v2/request/Merchant/MERCHANT_ID/diagnose https://checkout.google.com/api/checkout/v2/request/Merchant/MERCHANT_ID/diagnose
When you post a diagnostic message, Google parses the request and returns a <diagnosis> response, which indicates whether the API response contained any errors.
You can use curl to send diagnostic requests to Google. For example, you could save the API request in a file and then send it to Google using HTTP Basic Authentication with the following command. Please note that you must use the appropriate URL from the list above for your request. You must also replace the FILENAME, MERCHANT_ID and MERCHANT_KEY strings with the proper values.
curl -d '@FILENAME' https://MERCHANT_ID:MERCHANT_KEY@checkout.google.com/api/checkout/v2/request/Merchant/MERCHANT_ID/diagnose
Google Checkout returns an immediate response to server-to-server API requests that you post to Google, including server-to-server Checkout API requests, Order Processing API requests and diagnostic requests. The immediate response indicates whether your XML request is valid. A valid request must conform with the Google Checkout XML schema and must also request a legitimate action. For example, a <charge-order> request that instructs Google to charge the customer for more than the total price of an order would be invalid even if it conformed to the Google Checkout XML schema.
If your request is valid, Google returns one of three types of responses:
If you sent a valid server-to-server Checkout API request, Google will return a <checkout-redirect> response. This response is described in step iv of the section that explains server-to-server Checkout API requests.
If you sent a valid Order Processing API request, Google will return a <request-received> response. Please note that this message only indicates that your request is valid. It does not indicate that your request has been successfully processed. The following XML shows a sample <request-received> response:
<?xml version="1.0" encoding="UTF-8"?> <request-received xmlns="http://checkout.google.com/schema/2" serial-number="58ea39d3-025b-4d52-a697-418f0be74bf9"/>
If you sent a valid diagnostic request, Google will return a <diagnosis> response. This response indicates that the API request contained valid XML and that the request was sent to the proper diagnostic URL. For example, the URL would have to contain the correct Merchant ID. The following XML shows the format of a <diagnosis> response. Please note that the <input-xml> tag will contain the complete XML document that you sent to Google in your diagnostic request.
<?xml version="1.0" encoding="UTF-8"?> <diagnosis xmlns="http://checkout.google.com/schema/2" serial-number="49ba18e3-016b-4c52-a697-159a3lk38bf9"> <input-xml> <charge-order google-order-number="552406916759246"> <amount currency="USD">5.51</amount> </charge-order> </input-xml> </diagnosis>
If your request is not properly formed or requests an invalid status change, Google Checkout will return an <error> response to your request.
There are two types of reasons that a properly formed XML request would return an error:
Invalid argument errors occur when a value in a request is not in the range of valid values. For example, requesting a refund for more than the total amount of an order would trigger an invalid argument error.
Invalid state change errors occur when an order processing command cannot be executed on the order in its current state. For example, if you have already charged a customer for an order, you must issue a <refund-order> request before you can issue a <cancel-order> request.
The following XML shows a sample <error> response:
<?xml version="1.0" encoding="UTF-8"?> <error xmlns="http://checkout.google.com/schema/2" serial-number="3c394432-8270-411b-9239-98c2c499f87f"> <error-message>Bad username and/or password for API Access.</error-message> </error>
To help you monitor and debug your Google Checkout implementation, the Merchant Center displays a list of error messages that Google Checkout returned in response to your API requests. To see this list, log in to your Merchant Center account and click on the Settings tab. Then click on the Integration link in the menu on the left side of the page. The error log displays at the bottom of the Integration page. Learn more about the Integration Issues Console.
A Checkout API request sends order information from your website to Google, thereby enabling your customer to complete an order using Google Checkout. The following XML shows a simple Checkout API request:
<?xml version="1.0" encoding="UTF-8"?> <checkout-shopping-cart xmlns="http://checkout.google.com/schema/2"> <shopping-cart> <items> <item> <item-name>HelloWorld 2GB MP3 Player</item-name> <item-description>HelloWorld, the simple MP3 player</item-description> <unit-price currency="USD">159.99</unit-price> <quantity>1</quantity> </item> </items> </shopping-cart> <checkout-flow-support> <merchant-checkout-flow-support> <shipping-methods> <flat-rate-shipping name="SuperShip Ground"> <price currency="USD">9.99</price> </flat-rate-shipping> </shipping-methods> </merchant-checkout-flow-support> </checkout-flow-support> </checkout-shopping-cart>
A Checkout API request contains two main sections:
The <shopping-cart> element contains the list of items in the customer's shopping cart. You can specify the following information for each item in the cart:
The name of the item.
A description of the item.
The per-unit cost of the item.
The number of units of the item that the buyer is ordering.
A value, such as a SKU, that you use to uniquely identify the item.
An alternate tax table that should be used to calculate tax for the item. If you do not specify an alternate tax table for an item, Google Checkout will use your default tax table to calculate tax for the item.
A flag indicating that the item is a digital good and additional information that explains how the customer will be able to access the digital content after completing the order. If you sell digital goods, please see the Digital Delivery feature document for more information about formatting Checkout API requests to sell digital goods.
Additional, proprietary information that you would like associated with the item in the order. This information will not be displayed to the buyer but will be included in subsequent API exchanges that include information about the order.
The <checkout-flow-support> element contains additional information that is needed during the checkout process, such as your shipping options and tax tables. Please see the following sections of this document for additional information about checkout-flow-support features:
Google Checkout allows you to provide one or more shipping options for an order. The <shipping-methods> tag in your Checkout API request contains the set of shipping methods that you offer. If you specify more than one shipping option in a Checkout API request, Google Checkout will display a pulldown menu that lists those options on the Place Order page. The customer will need to select a shipping option from the menu before completing the order.
You can also specify that an item is a digital good. While digital delivery is discussed in the list below, please note that the Checkout API request does not place information about digital delivery in the <shipping-methods> tag in your XML request.
The following list identifies the different types of shipping options that you may specify in a Checkout API request. Each item in the list links to a separate document that fully describes the type of shipping method and also provides XML examples for that type of method. You must specify a unique name for each shipping option. You must also provide the default cost for each option.
Flat-rate shipping - For flat-rate shipping methods, a change in the shipping address does not affect the shipping cost for the order. You can use shipping restrictions to limit the geographic areas where a flat-rate shipping option is available.
Merchant-calculated shipping - For merchant-calculated shipping, you must operate a web service that calculates and returns shipping costs. Google Checkout will send your service a request containing the buyer's shipping address, the items in the order and the shipping methods that you offer. (You would have previously sent the items and shipping methods to Google in a Checkout API request.) Your web service then calculates the shipping cost for each shipping method and returns that information to Google.
Note: If you offer merchant-calculated shipping options for an order, you may not also provide other types of shipping options for that order, including flat-rate or carrier-calculated shipping options. For merchant-calculated shipping options, the default shipping cost is only used if the merchant calculation callback request fails for any reason.
Carrier-calculated shipping - For carrier-calculated shipping methods, you identify one or more FedEx, UPS or USPS shipping methods that you offer. Google will then dynamically calculate the shipping cost for each option based on the total weight of the items in your shopping cart. The carrier-calculated shipping document defines the specific shipping methods that Google supports for each of these carriers. For carrier-calculated shipping options, the default shipping cost is only used if Google fails in its attempt to obtain the carrier's shipping rates.
Pickup - For this type of shipping method, your customer picks the item up from your business. The customer does not need to specify a shipping address for this type of shipping. You can combine pickup shipping with a flat-rate shipping option for order delivery.
Digital delivery - Unlike physical goods, digital goods do not need to be shipped (or picked up in a store). The Checkout API allows you to identify digital goods on an item-by-item basis and to deliver digital goods online.
Note: If you do not include shipping information in a Checkout API request, Google Checkout will not charge the customer for shipping or handling. In addition, the method that you will use to ship the order may not be clearly communicated to the customer.
The following XML excerpt shows how you would provide a set of shipping options in a Checkout API request. This example specifies two flat-rate shipping options. This request uses shipping restrictions to limit the availability of these shipping options based on the buyer's shipping address. Please see the separate documents discussing flat-rate shipping, merchant-calculated shipping, carrier-calculated shipping and pickup for more examples of shipping methods in Checkout API requests.
The first option, UPS Next Day Air, specifies a cost of $20.00. This option uses shipping restrictions to specify that the option is only available in the continental United States. This option is also unavailable if the shipping address is a P.O. box.
The second option, UPS Ground, specifies a cost of $15.00. This option uses shipping restrictions to specify that the option is not available for shipping addresses in Minnesota. This option is also unavailable if the shipping address is a P.O. box.
<shipping-methods> <flat-rate-shipping name="UPS Next Day Air"> <price>20.00</price> <shipping-restrictions> <allow-us-po-box>false</allow-us-po-box> <allowed-areas> <us-country-area country-area="CONTINENTAL_48"/> </allowed-areas> </shipping-restrictions> </flat-rate-shipping> <flat-rate-shipping name="UPS Ground"> <price currency="USD">15.00</price> <shipping-restrictions> <allow-us-po-box>false</allow-us-po-box> <excluded-areas> <us-state-area> <state>MN</state> </us-state-area> </excluded-areas> </shipping-restrictions> </flat-rate-shipping> </shipping-methods>
Google Checkout calculates taxes based on tax rules that you include in your Checkout API request. Every tax rule must specify the geographic area where the rule applies as well as the tax rate that should be charged in that area. You can specify tax rates that are different for each item in an order, and you can apply those tax rates in areas as small as a postal or zip code or as large as the world. Checkout API requests can specify two different types of tax rules.
Default tax rules identify tax rates that will be applied, by default, in a particular geographic area. Default tax rules may also specify an optional tag, <shipping-taxed>, that indicates whether tax rates apply to shipping costs. Default tax rules are grouped into a default tax table, and each Checkout API request may contain one default tax table. You can override your default tax rules by specifying an alternate tax rule that should be used to calculate tax for an item.
Alternate tax rules identify tax rates that are applied to particular types of products. For example, a state may tax food items at a different rate than manufactured goods. In a Checkout API request, an alternate tax table contains all alternate tax rules that apply to a particular type of product or service. A Checkout API request may contain zero or more alternate tax tables.
As such, alternate tax rules are only relevant to merchants that charge different tax rates, depending on the type of item being purchased, in a single geographic area. The Defining Tax Tables document provides additional instructions and XML examples for creating alternate tax tables.
To select the tax rate for an item, Google Checkout will select the first default-tax-rule in the API request for which the tax-area matches the shipping address. (If you specify a tax-table-selector for the item, Google Checkout will select the first alternate-tax-rule for which the tax-area matches the shipping address.)
As such, your tax tables should list tax rules that apply in more specific geographic areas before rules that apply in less specific areas. For example, if a state has a 4 percent sales tax rate and a zip code in that state has an 8 percent sales tax rate, your API request should list the tax rule for the zip code before the tax rule for the state.
The Defining Tax Tables document provides an XML example that demonstrates the proper way to order tax rules.
For all financial calculations, Google Checkout uses a default rounding policy that is selected based on the merchant's home country. The Defining Tax Tables document explains how to change the rounding policy used to calculate totals for an order.
For U.S. merchants, Google Checkout uses banker's rounding as its default policy. Banker's rounding is the same as the traditional method of rounding numbers with one exception. In banker's rounding, if the number to be rounded is followed by a five and no additional nonzero digits, the number is rounded to the nearest even number. The following examples demonstrate the expected behavior in banker's rounding:
For U.S. merchants, Google calculates the total amount of tax for all of the items in an order and then uses banker's rounding to round that amount to two decimal places.
For U.K. merchants, Google Checkout uses the HALF_UP rounding mode. For this rounding mode, if the number being rounded is followed by a five and no additional nonzero digits, then that number is rounded up. All other numbers are rounded to the nearest digit. The following examples demonstrate the expected behavior for HALF_UP rounding:
For U.K. merchants, Google calculates tax for each item in the order and then uses HALF_UP rounding for each calculated amount.
Google Checkout provides several ways for merchants to offer coupons, gift certificates, or discounts:
Use the Merchant Calculations API to compute discounts after the buyer reviews the order. If you choose this option, the customer will have the option to enter coupon or gift certificate codes on the Google Checkout Place Order page. This option requires you to create and operate a fast, highly reliable web service to compute discounts. (That service could also calculate tax and shipping costs.) Please see the Merchant Calculations API section for more information.
Note: Merchants in the U.K. cannot yet use the Merchant Calculations API to calculate coupons or gift certificates.
Use the Google Checkout Coupon Creator to create coupons that your customers can enter through Google Checkout. The Coupon Creator offers the following features:
Buyers can enter one coupon per order for coupons created through the Google Checkout Coupon Creator.
Pass the discount as a separate item in the buyer's shopping cart with a negative price. This technique limits discounts to a fixed value that you must know at the time that you send the order information to Google Checkout. The following XML example shows how to include a discount in a Checkout API request. (Note that the <unit-price> tag has a negative value.)
<item> <item-name>$5 off all Valentines Day Orders</item-name> <item-description>Save $5 today only!</item-description> <unit-price currency="USD">-5.00</unit-price> <quantity>1</quantity> </item>
Note: If you accept coupons on your site, you must allow Google Checkout buyers to use those coupons, in accordance with Google Checkout Program Policies and Guidelines, section 2d.
When you post a Checkout API request, Google Checkout verifies that the XML in the request is valid. If the request is invalid, Google Checkout will reject the shopping cart.
In addition, Google Checkout performs several other checks to verify the integrity of the information in the API request. If the request does not pass these checks, Google Checkout will reject the shopping cart. However, these checks can not be enforced through the Google Checkout XML Schema. As such, a Checkout API request that is valid according to the XML schema will still be rejected if it fails to pass any of the following tests:
Checkout API requests may not include two or more shipping methods that have the same name. Shipping method names are contained in the name attribute value for the <merchant-calculated-shipping>, <flat-rate-shipping> and <pickup> XML elements. To verify that all names are unique, Google Checkout trims whitespace characters from the beginning and the end of the name string. Google Checkout then does a case-insensitive comparison of the names to ensure that they are unique. For example, Google Checkout would consider all of these names to be identical:
Regular shipping
REGULAR SHIPPING
Regular shipping
ReGuLaR sHiPPing
Checkout API requests may not mix a merchant-calculated shipping option with either flat-rate shipping or pickup shipping options. However, you may offer more than one merchant-calculated shipping option. You may also offer flat-rate and pickup shipping options together as long as they are not combined with merchant-calculated shipping options.
Checkout API requests that do not specify a <merchant-calculations-url> may not contain information suggesting that merchant calculations are required. A request will be rejected if it does not specify a <merchant-calculations-url> and either of the following conditions apply:
If you are using the Merchant Calculations API to calculate shipping costs or taxes for an order, you must specify backup shipping and tax amounts in your Checkout API requests. If a merchant calculation fails for any reason, Google will use these backup values when charging taxes and shipping for the order.
Specify a backup shipping cost for a merchant-calculated shipping option using the <price> tag. If you have more than one merchant-calculated shipping option, you may specify a different backup price for each option.
Specify backup tax amounts by providing a complete set of tax tables in your Checkout API request. If the merchant calculation fails, Google will calculate tax for the order using the default and alternate tax tables in the Checkout API request.
Note: This section is only relevant for merchants who need to perform proprietary calculations to determine taxes, shipping costs or discounts associated with coupons or gift certificates. If you are not implementing the Merchant Calculations API, please skip ahead to the Notification API section.
The Merchant Calculations API enables you to use your own business logic to compute order totals using information that is not known when you post a Checkout API request. You can use this API to compute taxes, shipping costs, and price adjustments from coupons or gift certificates. To use this API, you must build and operate a fast, highly reliable web service that calculates these values.
The following steps explain how the Merchant Calculations API works.
Your Checkout API request uses specific tags to indicate that you will perform custom calculations for an order. You can decide whether to calculate shipping costs, taxes and price adjustments, or only some of those values.
Note: Even if you intend to calculate tax or shipping costs, you should still include default shipping costs, default tax tables and alternate tax tables in your Checkout API request. These shipping costs and tax tables will only be used if the request to your web service fails for any reason. (If you do not provide default values and the calculation request fails, Google will not add tax and shipping charges to the order.) Google recommends that you use average or typical rates for your default values as described in section 2 of the Google Checkout Policies and Guidelines.
Google Checkout sends a merchant-calculation-callback request to your web service each time that any of the following events occur.
Upon receiving a merchant-calculation-callback request, your web service verifies that the request is authenticated with your Merchant ID and Merchant Key. Your service should not process the request if it cannot be authenticated.
Note: Google Checkout uses SSL to send merchant-calculation-callback requests. As such, your web service must use HTTPS and you must have a valid SSL certificate. Your production service for handling merchant calculation callbacks must use port 443, which is the default port for HTTPS. In the Sandbox environment, you can use either port 443 or port 80 for your merchant calculation callback service. For additional security requirements, please see the Sending API Requests with HTTP Basic Authentication section of this document.
Your web service calculates shipping costs, taxes and discounts based on the information in the merchant-calculation-callback request. Your web service then generates and returns a merchant-calculation-results response, which contains the calculated amounts.
Note: Google allows three seconds for your calculations service to perform any necessary calculations and return a merchant-calculation-results response. If the merchant calculation fails for any reason, or if Google does not receive a response within three seconds, Google will use the backup tax and shipping values specified in the Checkout API request.
You cannot specify backup amounts for coupons and gift certificates. If the calculation fails and the customer entered coupon or gift certificate codes, Google Checkout will prompt the customer to resubmit the coupon or gift certificate codes.
The Merchant Calculations API is described in a separate document titled Implementing the Merchant Calculations XML API. That document explains how to specify in a Checkout API request that you will calculate shipping costs, taxes and price adjustments. That document also defines the format of the merchant-calculation-callback request and the merchant-calculation-results response. Finally, that document provides sample XML for all of these API requests and responses.
Note: The Notification API and Order Processing API sections of this document are only relevant for merchants that are completing order processing integrations. Order processing integrations allow merchants to integrate Google Checkout with internal order processing systems. If you are not implementing these APIs, please skip ahead to the Using the Google Checkout Merchant Center section.
Google Checkout uses the Notification API to inform you of a new order or to send you information about an existing order. The Notification API lets you integrate Google Checkout with your internal order fulfillment systems by allowing those systems to receive order information from Google. Typically, merchants choose to simultaneously integrate the Notification API and the Order Processing API, which allows you to send Google updated information about an order's financial state or its fulfillment state.
Each Google Checkout notification is an XML document that constitutes the body of an HTTP POST request. To implement the Notification API, you must build and operate a web service that receives Google Checkout notifications and then communicates the details of those notifications to your internal order processing systems.
The following list identifies the different types of notifications that the API supports. Each item in the list links to a section that describes the notification and provides sample XML for that notification.
New Order Notifications inform you of new orders that have been submitted through Google Checkout.
Risk Information Notifications provide financial information about a transaction to help you ensure that an order is not fraudulent.
Order State Change Notifications signal an update to an order's financial status or its fulfillment status.
Amount Notifications inform you that a charge, refund, chargeback or credit card authorization has been processed for an order. These notifications also identify the amount of the transaction.
The Notification API is described in full detail in a separate document titled Implementing the Notification API. That document explains how to authenticate API requests so that you can ensure those requests are valid before you process them. It also explains how Google will interpret your HTTP response to each notification to determine whether you handled the notification successfully. That document proceeds to describe each of the different types of notifications and includes a sample for each notification type.
Note: This section is only relevant for merchants who are integrating Google Checkout with their internal order processing systems. If you are not implementing the Notification API or the Order Processing API, please skip ahead to the Using the Google Checkout Merchant Center section.
Each Google Checkout order has a financial-order-state and a fulfillment-order-state.
The financial order state identifies the stage of the payment process where the order is located. Valid financial states include CHARGEABLE, CHARGED and PAYMENT_DECLINED.
The fulfillment order state enables you to track orders through the fulfillment process and to convey the fulfillment status to the buyer. Valid fulfillment states are NEW, PROCESSING, DELIVERED and WILL_NOT_DELIVER.
The Order Processing API provides functions that enable you to change these states by integrating Google Checkout with your internal order processing systems. The Order Processing API defines three types of commands:
Financial commands enable you to authorize or perform credit card transactions for an order. Each of these commands affects an order's financial-order-state, which identifies the stage of the payment process where the order is located. The Order Processing API defines the following financial commands, all of which are explained in a separate document titled Financial Commands in the Order Processing API.
* The <cancel-order> command also changes an order's fulfillment order state.
Fulfillment commands let you communicate information about the stage of the fulfillment process where either an order or individual items within that order are located. You can use fulfillment commands to identify the items in an order that have shipped and to provide shipment tracking data for those items. If you specify a fulfillment state for each item in an order, then Google Checkout will use the statuses of those items to deduce the fulfillment state of the entire order. For example, if all of the items in an order have been shipped, then the order's fulfillment status will be DELIVERED.
The following lists identify the Order Processing API's fulfillment commands. The lists are separated to specify API commands used for either a line-item shipping API integration or an order-level shipping API integration. Two commands, <add-merchant-order-number> and <send-buyer-message>, are equally relevant to both integration methods and appear in both lists.
Google recommends that you integrate using the line-item shipping commands since these provide a better buyer experience. However, since these commands were introduced in August 2007, many merchants have already integrated using order-level shipping commands. Google Checkout will continue to support order-level shipping commands indefinitely.
Line-item shipping commands allow you to specify shipment tracking information on an item-by-item basis. Using line-item shipping commands, you can specify multiple shipments for an order and identify the items included in each shipment. Line-item shipping commands also let you identify individual items in an order that are out-of-stock as well as items that have been canceled from an order or returned by the customer.
The Order Processing API defines the following line-item shipping commands, all of which are explained in a separate document titled XML API Commands for Line-Item Shipping.
Order-level shipping commands let you provide shipment tracking information that applies to all of the items in an order. You can also use order-level commands to mark an entire order as delivered or canceled. For each order-level shipping command, you can use an line-item shipping command that provides the same functionality.
The Order Processing API defines the following order-level shipping commands, all of which are explained in a separate document titled XML API Commands for Order-Level Shipping.
* As noted above, the <cancel-order> command also changes an order's financial order state.
Note: Google recommends that you use line-item shipping commands rather than order-level shipping commands because line-item commmands provide a better buyer experience. Line-item shipping commands also allow you to more easily track orders that have multiple shipments as well as returned, canceled or backordered items.
Archiving commands enable you to manage the list of orders in your Merchant Center inbox. Archiving commands do not have any impact on an order's status or on the order information that is communicated to the customer.
The Order Processing API defines the following archiving commands, both of which are explained in a separate document titled XML API Commands for Archiving Orders.
Merchants who use the Order Processing API can also still use the Merchant Center to trigger order state changes. For example, you could use the Order Processing API for common events, such as charging orders, and the Merchant Center for unusual events like initiating a refund.
Order Processing API requests must meet the following requirements:
We also strongly recommend that you verify the authenticity of the server certificate that is presented to you when you make the HTTPS connection with Google. Please verify the items in the checklist below before sending any data or doing HTTP Basic Authentication.
The Merchant Center is an online interface that allows you to view and manage orders placed through Google Checkout. The screenshot below shows the Inbox page in the Merchant Center, which displays active – nonarchived – orders for a merchant. This page displays the financial and fulfillment states for your orders. On this page, the Chrg column identifies the financial status of the order. The Ship column identifies the fulfillment status of the order.
Merchant Center Inbox
The Merchant Center Inbox displays the following icons in the Chrg and Ship columns:
|
Chrg column values
|
Ship column values
|
* The partial shipment icon only displays for merchants that are using line-item shipping commands.
The screenshot below shows the order details for an order containing three items. One of the three items is backordered, one has been returned and the third was cancelled. The screenshot shows that the order has been divided into two shipments.
Merchant Center Order Details
Note: The Merchant Center in the Google Checkout Sandbox displays a background image to indicate that you are working in the Sandbox environment.
An order's financial-order-state and fulfillment-order-state appear in the following three places in the Merchant Center:
The following table shows the mapping between order states and the text that appears in the Merchant Center.
| API Order State | Text in Merchant Center |
||
| Inbox Status column | Inbox Items column | Invoice page | |
| Financial order states: | |||
| REVIEWING | Reviewing... | Reviewing... | |
| CHARGEABLE | Chargeable | ||
| CHARGING | Charging... | Charging... | |
| CHARGED | Charged: (amount) for partial charge only |
Charged | |
| PAYMENT_DECLINED | Payment declined: buyer contacted | Payment Declined | |
| CANCELLED | Cancelled | Cancelled | |
| CANCELLED_BY_GOOGLE | Cancelled by Google: payment declined or Cancelled by Google: high risk order |
Payment Declined | |
| Fulfillment order states | |||
| NEW | New | New | |
| PROCESSING | Processing | Processing | |
| DELIVERED | Shipped | Shipped | |
| WILL_NOT_DELIVER | Cancelled | Cancelled | |
A blank cell indicates that a state is not shown in the given location. For example, the CHARGEABLE state does not appear in the Status or Items column in the inbox.
For some orders, the Merchant Center displays additional information about the order that is not represented by order states. For example, the Merchant Center may provide more information about an order that is being refunded or charged back.
The Merchant Center includes an Integration Issues console that identifies the errors and warnings from the API requests that you have sent to Google Checkout. Errors and warnings appear in the console as they occur, enabling you to debug errors as they occur. The console will display error and warning messages from the previous seven-day period. If there are more than 1000 errors and warnings from the previous seven days, only the most recent 1000 messages will be accessible.
We recommend you check the console frequently while you are integrating Google Checkout into your website. After launching your Google Checkout integration, you should check the console periodically to ensure that your integration is working as you expect.
To locate the Integration Issues console, log in to your Merchant Center account and click the Tools tab. The console, which is shown in the diagram below, displays in the center of the page.
You can use the console to debug errors in your test environment or your production environment. To view errors in your test environment, log in to your Sandbox account. To view errors in your production environment, log in to your Google Checkout account.
Note: Google Checkout will only log errors for API requests that you send to a valid URL for posting API requests.
If you click on the description for an error or warning, you will be directed to a page that displays more information about the issue. That page will display the date and time that the issue occurred, the error or warning message that Google returned, the request that Google received and the response that Google returned. The screenshot below shows a sample Integration Issue Detail page:
This section describes several techniques that you can use to test your integration and to troubleshoot problems that you encounter. This section reviews Google Checkout tools discussed earlier in this document and also introduces other tools that you can use for testing and troubleshooting.
The Integration Issues console in the Merchant Center identifies the errors and warnings generated by API requests that you have sent to Google Checkout. Errors and warnings appear in the console as they occur, enabling you to debug errors as they occur.
Google Checkout provides a diagnostic feature that lets you validate Checkout and Order Processing API requests without actually submitting them. The Validating XML Messages to Google Checkout section explains how to use this feature.
You can perform basic experiments with the Google Checkout API using curl, an open-source tool for communicating with servers that use HTTP and other protocols. The Getting Started with Google Checkout section – see step 4 – explains how to use curl to ensure that your server can communicate with Google Checkout.
You can also use curl to test other API requests. The Validating XML Messages to Google Checkout section explains how to save an API request in a file and then use the @ option in curl to post the contents of that file to Google. When you submit a request, you will see Google Checkout's immediate response to that request. If you test server-to-server Checkout API requests, the response will contain a redirect URL that you can follow to see the order in your browser.
For more information about curl, see http://curl.haxx.se/.
The <demo-failure> request enables you to test your application's ability to handle error messages from Google Checkout. Google returns an <error> response for any <demo-failure> request. The response's <error-message> element contains the string "Failed as expected with:" followed by the text you provided in the message attribute of the <demo-failure> tag.
The following XML shows a sample <demo-failure> request:
<?xml version="1.0" encoding="UTF-8"?> <demo-failure xmlns="http://checkout.google.com/schema/2" message="test error handling"> </demo-failure>
This request yields the following <error> response:
<?xml version="1.0" encoding="UTF-8"?> <error xmlns="http://checkout.google.com/schema/2" serial-number="6dcd58ae-3411-4383-a4ee-9a38d7d4f0a8"> <error-message>Failed as expected with: test error handling</error-message> </error>
Google Checkout provides a testing feature for the sandbox environment that enables you to submit an order that will return a specific type of Address Verification System (AVS) response or credit verification value. The feature also lets you specify that Google Checkout should send an order state change notification indicating that the credit card for a sandbox order was either authorized or rejected. This feature is described in the Google Checkout Credit Card Test Cases document.
The order has not been charged.
The order has been partially charged.
The order has been fully charged.
The order has been canceled.
The buyer's credit card has been declined.