| Note: This is the latest documentation. The previous version is available. The order processing section has been moved to a new page. |
Note: The HTML API can be used directly with Buy Now buttons, contribute buttons, donor buttons and custom carts. It can be used with Checkout shopping cart only with the use of a wrapper. It cannot be used with store gadgets.
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 HTML 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 HTML 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 HTML API. This section also contains a technical discussion that explains how you convey order information to Google.
The API Reference section explains how to submit API requests to Google and also explains the responses that Google sends to an API request. In addition, this section explains how to use HTTP Basic Authentication to send certain types of API requests.
The Checkout API section provides specific details about the different Google Checkout APIs. It links to one or more additional documents that contain instructions for implementing specific API features.
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.
Note: The following list contains short attribute names, which link to their equivalent long attribute name.
The target URL for the Change order link is the value of the edit_url parameter.
The Qty column displays the value of the item_quantity_# parameter for each item in the order.
The bold text in the Item column displays the value of the item_name_# parameter 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 item_price_# parameter as well as the symbol associated with the value of the item_currency_# parameter for each item in the order.
The pulldown menu in the Shipping & Handling row displays a list of the shipping methods that you offer, which are contained 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 you have defined coupons using the Google Checkout Coupon Creator.
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 your test merchant account at https://sandbox.google.com/checkout/sell to locate your Merchant ID and your Merchant Key. You will need both of these values to test your Google Checkout integration. You will use both values to encode order information before submitting that information to Google Checkout.
After signing in to your 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.
Note: You should never share your Merchant Key with anyone, 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 in your terminal window. Substitute S_MERCHANT_ID and S_MERCHANT_KEY with your Sandbox ID and key; P_MERCHANT_ID and P_MERCHANT_KEY with your production ID and key;
Test the Sandbox account: (enter on one line) curl -d '_type=hello' https://S_MERCHANT_ID:S_MERCHANT_KEY@sandbox.google.com/checkout/api/checkout/v2/requestForm/Merchant/S_MERCHANT_ID Test the production account: (enter on one line) curl -d '_type=hello' https://P_MERCHANT_ID:P_MERCHANT_KEY@checkout.google.com/api/checkout/v2/requestForm/Merchant/P_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 HTML excerpt shows a sample <bye> response:
_type=bye &serial-number=e5d9064a-8eb3-43c5-8211-36ecbe96453a
Under the Shopping cart post security header, uncheck the box to allow your account to use API requests with name-value pairs. After removing the check from the checkbox, click the Save button to save your settings.
Note: You must confirm that you will post unsigned shopping carts for your sandbox account and your production account. You must use the XML API if you want to post digitally signed shopping carts.
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. However, each button must be contained within a form that submits to Google Checkout.
There are two ways to send this information to Google Checkout.
Use hidden input fields to add order information to the form that displays the Google Checkout button. The form will also need to contain hidden input fields that contain information about the shipping options that the customer can select and the taxes that should be added to the order. If you use this method, then the forms that display Google Checkout buttons will submit directly to Google Checkout.
Ensure that your form submits orders to the correct URL.
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 merchant account will have a different Merchant ID and Merchant Key than your Sandbox merchant 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 merchant 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.
Direct the forms that display Google Checkout buttons to a page on your site. That page will send Google an HTTP POST request containing the customer's order information. Google will reply to your request with a Google Checkout URL to which you will redirect the customer. Please see the section that explains server-to-server API requests for complete instructions on using this approach to send order information to Google.
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/checkoutForm/Merchant/1234567890">
<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 The Buy Now button will contain all of the 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.
Google provides a suite of 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 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.
As noted above, you must implement the Checkout API to integrate with Google Checkout. 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.
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 consists of a series of key-value pairs that provide 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 HTML sample shows a very simple order. This request defines a shopping cart that contains one item and offers two shipping options. 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 HTML examples.
<input type="hidden" name="item_name_1" value="5 lbs. Dog Food"/> <input type="hidden" name="item_description_1" value="5 lb. bag of nutritious Dog Food"/> <input type="hidden" name="item_price_1" value="35.00"/> <input type="hidden" name="item_currency_1" value="USD"/> <input type="hidden" name="item_quantity_1" value="1"/> <input type="hidden" name="item_merchant_id_1" value="5LBDOGCHOW"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.name" value="UPS Next Day Air"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price" value="20.00"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price.currency" value="USD"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.name" value="UPS Ground"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price" value="15.00"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price.currency" value="USD"/>
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 allows you 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 use hidden <input> fields to embed all of the customer's order information on every web page that displays a Google Checkout button.
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 a Checkout API request containing product, shipping and tax 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 HTTP request containing information using name/value pairs about the customer's order. The names should be from attribute (parameter) names in the HTML API.
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 Checkout API request to Google using an HTTP POST request. Please select the appropriate URL for your request from these two choices:
Sandbox - 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
Production - 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 HTML, Google will return a checkout-redirect response. This message identifies the Google Checkout URL where the customer can complete the order. The following HTML shows a sample checkout-redirect response.
_type=checkout-redirect &serial-number=c821326e-7caa-4d51-9b2e-48ef7ecd6423 &redirect-url=https://checkout.google.com/buy&8572098456
Note: The URL may include an ampersand (&) character, encoded as & in the HTML. Your HTML 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 HTML-decoded URL that you received in step 4.
The following sections provide general details about the information that you will send to and receive from Google Checkout. These sections explain the following information:
The names for the input parameters used in the HTML API correlate very closely to the names of the elements in the Google Checkout XML schema. The list below specifies key characteristics of HTML API requests and field names:
Each API request contains the _type field, which specifies the type of API request being submitted. For example, in a Checkout (Shopping Cart) API request, the value of the type field is checkout-shopping-cart. In the XML API, the <checkout-shopping-cart> tag is the root tag in a Checkout API request.
Similarly, for any other API request, the value of the _type field equals the name of the root XML tag used to execute the same request in the XML API. For example, the root XML tag for a risk information notification is <risk-information-notification>. As such, the value of the _type parameter would be risk-information-notification.
The HTML parameter name for an element in the XML schema reflects the path to that element in a tree representation of the XML schema. The name is constructed using the following conventions:
Combine the names of the elements in the path to create the parameter name for an element. The parameter name begins with the first element below the root tag, which is identified separately using the _type parameter, and element names are separated using periods (.). For example, the continue-shopping-url field appears in a Checkout API request. In an XML API request, this value appears in the following context:
<checkout-shopping-cart>
<checkout-flow-support>
<merchant-checkout-flow-support>
...
<request-buyer-phone-number>true</request-buyer-phone-number>
...
</merchant-checkout-flow-support>
</checkout-flow-support>
</checkout-shopping-cart>
In an HTML API request, the field uses the following format:
checkout-flow-support.merchant-checkout-flow-support.request-buyer-phone-number=true
Some XML elements can recur in a normal request. For example, an order may contain more than one item, and you might charge tax in more than one state.
To represent a recurring XML element in an HTML parameter name, you must associate an index number with that element in the HTML parameter name. For example, the following example shows HTML parameters for two items. The XML schema allows the <item> tag to recur in an API request. As such, in an HTML parameter name, you must append -# to the element name item, replacing the pound (#) symbol with the item's index number in the list. Please use the number 1 to identify the first item in a list. The following fields demonstrate how you would provide the name and description for two different items in an HTML API request:
_type=checkout-shopping-cart &shopping-cart.items.item-1.item-name=Peanut%20Butter &shopping-cart.items.item-2.item-name=Strawberry%20Jelly &shopping-cart.items.item-1.item-description=Made%20from%20peanuts &shopping-cart.items.item-2.item-description=Made%20from%20strawberries
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.
The following URLs are used for 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/checkoutForm/Merchant/MERCHANT_ID https://checkout.google.com/api/checkout/v2/checkoutForm/Merchant/MERCHANT_ID
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.
Please note that Google also uses HTTP Basic Authentication to send 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 HTML file for the command being executed.
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 to generate your authorization key.
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 HTML 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.
Google Checkout provides a diagnostic feature that lets you verify that Checkout API requests are valid without actually submitting those requests. To use this feature, construct the HTML for the API request and then submit it to Google Checkout's validator by appending /diagnose to the submission URL.
For Checkout API requests, use the following URLs. 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/checkoutForm/Merchant/MERCHANT_ID/diagnose https://checkout.google.com/api/checkout/v2/checkoutForm/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
The sample file below shows how to format a file that you will post to Google using curl or a similar application. This file simulates a form-based request. The file shows a series of name=value pairs. Each name=value pair after the first pair is preceded by an ampersand. The name=value pairs could all appear on the same line or each could be printed on its own line as shown in the sample.
item_name_1=Dog%20Food &item_description_1=Yummy%20bacon%20flavor &item_quantity_1=1 &item_price_1=10 &item_currency_1=USD
You could also write a script to submit a diagnosis request that simulates a server-to-server Checkout API request. For example, the Perl script below posts a series of name=value pairs to Google Checkout and then evaluates the response to determine whether the request was valid.
#!/usr/bin/perl -w
use LWP::UserAgent;
my $lwp = LWP::UserAgent->new;
my $id = "1234567890"; # Replace 1234567890 with your merchant ID
my $url = "https://checkout.google.com/api/checkout/v2/checkoutForm/Merchant/$id/diagnose";
my $response = $lwp->post($url, [[]'item_name_1' => 'Dog Food',
'item_description_1' => 'Yummy bacon flavor',
'item_quantity_1' => '1',
'item_price_1' => '10',
'item_currency_1' => 'USD']);
if ($response->is_success) {
print "This request is valid.";
} else {
my @error_array = split(/&/, $response->content);
foreach my $parameter (@error_array) {
my @name_value = split(/=/, $parameter);
print "Name: " . $name_value[[]0] . ", value:" . $name_value[[]1] . "\n";
}
}
Google Checkout returns an immediate response to server-to-server API requests that you post to Google, including server-to-server Checkout API requests and diagnostic requests. The immediate response indicates whether your HTML request is valid. A valid request must conform with the Google Checkout HTML 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 diagnostic request, Google will return a diagnosis response. This response indicates that the API request contained valid HTML 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 HTML shows the format of a diagnosis response. Please note that the response will contain HTML parameters that return the information submitted in your diagnostic request. The example below shows the diagnosis response for a charge-order request. Each parameter from the original request is preceded by request.charge-order.
_type=diagnosis &serial-number=c821326e-7caa-4d51-9b2e-48ef7ecd6423 &request.charge-order.amount=5.51 &request.charge-order.amount.currency=USD
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 HTML 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, you must issue a refund-order request before you can issue a cancel-order request.
The following HTML shows a sample error response:
_type=error &serial-number=c821326e-7caa-4d51-9b2e-48ef7ecd6423 &error-message=Bad%20username%20or%20password%20for%20API%20Access.
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 HTML shows a simple Checkout API request:
<input type="hidden" name="item_name_1" value="5 lbs. Dog Food"/> <input type="hidden" name="item_description_1" value="5 lb. bag of nutritious Dog Food"/> <input type="hidden" name="item_price_1" value="35.00"/> <input type="hidden" name="item_currency_1" value="USD"/> <input type="hidden" name="item_quantity_1" value="1"/> <input type="hidden" name="item_merchant_id_1" value="5LBDOGCHOW"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.name" value="UPS Next Day Air"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price" value="20.00"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price.currency" value="USD"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.name" value="UPS Ground"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price" value="15.00"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price.currency" value="USD"/>
A Checkout API request contains two primary sets of information:
Shopping cart parameters describe 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.
Checkout-flow-support parameters describe 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. 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. If all of the items in an order are digital goods, then Google Checkout will not display shipping options for the items.
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 HTML 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.
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 HTML 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, 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.
<input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.name" value="UPS Next Day Air"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price" value="20.00"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.price.currency" value="USD"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.shipping-restrictions.allow-us-po-box" value="false"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-1.shipping-restrictions.allowed-areas.us-country-area-1.country-area" value="CONTINENTAL_48"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.name" value="UPS Ground"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price" value="15.00"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.price.currency" value="USD"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.shipping-restrictions.allow-us-po-box" value="false"/> <input type="hidden" name="checkout-flow-support.merchant-checkout-flow-support.shipping-methods.flat-rate-shipping-2.shipping-restrictions.excluded-areas.us-state-area-1.state" value="MN"/>
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 parameter, 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 HTML 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 HTML 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 two ways for merchants to offer coupons, gift certificates, or discounts:
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 HTML example shows how to include a discount in a Checkout API request. (Note that the second item has a negative price.)
<input type="hidden" name="item_name_1" value="5 lbs. Dog Food"/> <input type="hidden" name="item_description_1" value="5 lb. bag of nutritious Dog Food"/> <input type="hidden" name="item_price_1" value="35.00"/> <input type="hidden" name="item_currency_1" value="USD"/> <input type="hidden" name="item_quantity_1" value="1"/> <input type="hidden" name="item_merchant_id_1" value="5LBDOGCHOW"/> <input type="hidden" name="item_name_2" value="Pet food coupon offer"/> <input type="hidden" name="item_description_2" value="$5 off all pet food orders!"/> <input type="hidden" name="item_price_2" value="-5.00"/> <input type="hidden" name="item_currency_2" value="USD"/> <input type="hidden" name="item_quantity_2" value="1"/>
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 request is valid. Even though you are using the Google Checkout HTML API, your API requests must still comply with the Google Checkout XML Schema. For example, the schema requires each item in a buyer's shopping cart to have a name and a price. To prevent you from needing to constantly refer to the XML schema to implement the HTML APIs, the definitions in the HTML Parameter Reference indicates whether each parameter is required or optional. 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 specified using the name hidden input parameter. 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
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 requests without actually submitting them. The Validating API Requests 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 API Requests 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 parameter element contains the text you provided in the message parameter.
The following HTML shows a sample demo-failure request:
POST https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID/diagnose
_type=demo-failure
&message=Return%20an%20error%20response
This request yields the following error response:
_type=form-diagnosis &request.demo-failure.message=Return+an+error+response &serial-number=21cc0488-3afb-4fda-83f2-369658100013
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 Integration Issues console in the Merchant Center 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:
