Google Checkout API

Documentation

XML API Developer's Guide

HTML API Developer's Guide

Using Google Analytics

Third-Party Conversion Tracking

Terms and Conditions

Developer Tools

Sample Code

XML Schema

Developer's Articles

Checkout Button URL Generator

Acceptance logos

Support Resources

FAQ

Developer's Forum

Blog

Google Checkout Sample Code for .NET

 

Google Checkout's sample code for .NET is distributed as a .zip file. This file contains classes and methods designed to construct Google Checkout API requests and handle Google Checkout API responses, notifications and merchant calculation callbacks. This code is intended to be integrated directly into your web application.

Contents

This page provides an overview of the Google Checkout .NET sample code. This page is divided into the following sections:

  • The System Requirements section identifies a list of prerequisites for merchants who plan to use this sample code in their Google Checkout implementations.

  • The Application Flow for Google Checkout .NET Sample Code section illustrates and explains the process of sending a Checkout API request using the .NET sample code.

  • The Installing the GCheckout Module section explains how to install and test the Google Checkout sample code for .NET.

  • The Complex Shopping Cart Example section provides sample code changes for submitting a complex shopping cart. After ensuring that your installation was successful, you can use this sample code to better understand how to create Checkout API requests and how your customer will interact with Google Checkout after clicking the Google Checkout button.

  • The Integrating the Sample Code into your Web Application contains general information about the code changes that you will need to make when integrating this sample code into your web application.

  • The Understanding the .NET Sample Code Distribution section provides a short description of each class (.cs) file included in the sample code distribution and links to pages that provide more complete documentation of the individual methods contained in those classes. These pages include a list of all of the methods in a particular class, including an explanation of each method, a list of that method's parameters and the method's code.

    The classes in the GCheckout.zip file correspond to the different types of API requests that you can send using Google Checkout. As such, you may be able to disregard certain classes if you are not using the APIs that those files implement.

Note: The sample code in this document uses the alternate method for posting Checkout API requests. This method is described in the Google Checkout Developer's Guide. The sample code uses this alternate technique because ASP.NET uses forms to handle events like button clicks, meaning many ASP.NET pages contain a form. Using the standard method of posting a Checkout API request might require you to add a second form to a page. However, since browsers do not support nested form elements, this approach would not work. The alternate technique for posting carts provides a solution to this problem.

About this Document

This documentation only covers the methods that you need to use to create Checkout API requests. Checkout API requests contain information about customer orders, including the items in a customers' shopping carts as well as tax rates and shipping options for those orders. However, the sample code distribution also includes methods that you can use to create and handle Order Processing, Notification and Merchant Calculations API requests. Additional documentation for those methods is coming soon.

The code in this documentation is all written in C#. Sample Visual Basic code for .NET is not available.

System Requirements

Google Checkout's sample code for .NET uses the following software. You may need to install these libraries or packages to incorporate this sample code into your Google Checkout implementation.

  • .NET Framework version 1.1 or higher
  • Internet Information Services (IIS) 5.1 or higher
  • Visual Studio 2003 or later (for developers who are using Visual Studio to implement Google Checkout)

Application Flow for Google Checkout .NET Sample Code

The following image illustrates the Google Checkout application flow.

This diagram shows the following steps:

  1. Your customer requests a web page on your site.

  2. Your web application returns the web page, which displays a Google Checkout button.

  3. Your customer clicks the Google Checkout button. By clicking the button, your customer sends her order to Google Checkout. (The next step the customer experiences will be step 9; in the meantime, your application will interact with the GCheckout.dll code and with Google Checkout to execute steps 4 through 8.

  4. The Google Checkout button's click handler calls methods in the GCheckout module that create the API request to send to Google Checkout.

  5. You call another method, instructing the GCheckout module to send the API request to Google Checkout.

  6. Google Checkout returns an XML response that includes the URL to which your customer should be redirected. This response is parsed by the GCheckout module.

  7. Your web application calls another method to extract the URL to which the customer should be redirected and to return this URL to the customer's browser.

  8. Your web application returns an HTTP 302 (redirect) response to the customer's web browser.

  9. The customer's browser sends a request to Google Checkout for the order confirmation page. This page is identified by the redirect URL.

Installing the GCheckout Module for Checkout API Requests

This section explains how to install and then test your installation of the GCheckout module for .NET implementations. This test verifies that the installed GCheckout module can submit a shopping cart order for your store in the Google Checkout Sandbox (test) environment. After completing the test, you will need to update some of the methods in the provided source code to actually integrate the GCheckout module with your web application.

Please choose the appropriate set of installation instructions from the following list:

Installing the GCheckout Module using Visual Studio

  1. Download the GCheckoutDLL.zip file. Extract the GCheckout.dll file from the zip file and copy it into the /bin directory of your web application. You can also download the source code used to compile the Checkout.dll.

  2. In Visual Studio, open the page that you will add the Google Checkout button to.

  3. Click on the General tab in the Visual Studio Toolbox. If the GCheckout button does not already appear, right click beneath the General tab and select Add/Remove Items from the dropdown menu.

    Note: The web application used in this screenshot and other screenshots in this document is a blank web page that is being modified to display a Google Checkout button.

    Click the Browse button and then locate the GCheckout.dll file, which should be in the /bin directory. Click Open to open the file and then click the OK button to close the browse window.

  4. The GCheckout button should now appear in the Toolbox underneath the General tab. Click the GCheckout button and drag it into your form. Place the button on the page in the location where you would like it to display.

  5. Right click on the icon and select Properties from the dropdown menu. This will open the properties window for the Checkout button.

  6. In the properties window, scroll down to the Google properties.

    You can set the following properties for the button:

  7. Double click on the web.config file listed in the Solution Explorer window.

    If you do not already have an <appSettings> section in your web.config file, add the following code after the <configuration> tag that starts the file.

    <appSettings>
    <add key="GoogleMerchantID" value="Your Merchant ID" />
    <add key="GoogleMerchantKey" value="Your Merchant Key" />
    <add key="GoogleEnvironment" value="Sandbox" />
    </appSettings>

    If you do already have an <appSettings> section in your web.config file, add this code inside the <appSettings> section.

    <add key="GoogleMerchantID" value="Your Merchant ID" />
    <add key="GoogleMerchantKey" value="Your Merchant Key" />
    <add key="GoogleEnvironment" value="Sandbox" />

    Note: You need to make these changes to the web.config file in your test environment and to the web.config file in your production environment. Each file must specify different values for the GoogleMerchantID, GoogleMerchantKey and GoogleEnvironment keys.

    You can find the merchant ID and merchant key to use in your test environment in your Sandbox account. To locate these values, log in to your Sandbox account, click on the Settings tab and then click on the Integration link in the menu on the left side of the page. In your test environment, the value of the GoogleEnvironment key should be Sandbox.

    You can find the merchant ID and merchant key to use in your production environment in your Google Checkout account. Again, log in to your account, click on the Settings tab and then click on the Integration link in the menu on the left side of the page. In your production environment, the value of the GoogleEnvironment key should be Production.

    The screenshot below shows the location of your merchant ID and merchant key in your Google Checkout account.

  8. Click back to your web form. Then double-click on the Google Checkout button on your form to open the code window, which will display the Checkout button's click handler. This is the code that will execute when the user clicks the Checkout button on your web page.

    Add the following code to the list of libraries at the top of the file:

    using GCheckout.Checkout;
    using GCheckout.Util;

    Then insert the following lines of code into the GCheckoutButton1_Click method:

    CheckoutShoppingCartRequest Req = GCheckoutButton1.CreateRequest();
    Req.AddItem("Snickers", "Packed with peanuts.", 0.75m, 2);
    GCheckoutResponse Resp = Req.Send();
    Response.Redirect(Resp.RedirectUrl, true);

  9. Start the application by either selecting Start from the Debug menu or by pressing the F5 key. You should see your page with a Google Checkout button displayed on the page.

  10. Click on the Google Checkout button to send a test request. You should be directed to a Google Checkout page that displays an order for two Snickers bars for a total cost of $1.50.

Installing the GCheckout Module using a Text Editor

  1. Download the GCheckoutDLL.zip file. Extract the GCheckout.dll file from the zip file and copy it into the /bin directory of your web application. You can also download the source code used to compile the Checkout.dll.

  2. In a text editor, open the page that you will add the Google Checkout button to.

  3. Add the following lines to the list of import statements at the top of the page. If the page does not already have import statements, add these lines at the beginning of the file.

    <%@ Import Namespace="GCheckout.Checkout" %>
    <%@ Import Namespace="GCheckout.Util" %>
    <%@ Register TagPrefix="cc1" Namespace="GCheckout.Checkout" Assembly="GCheckout" %>

  4. Add the following code inside the <script runat="server" language="C#"> tag.

    private void PostCartToGoogle(object sender, System.Web.UI.ImageClickEventArgs e) {
        CheckoutShoppingCartRequest Req = GCheckoutButton1.CreateRequest();
        Req.AddItem("Snickers", "Packed with peanuts", 0.75m, 2);
        GCheckoutResponse Resp = Req.Send();
        Response.Redirect(Resp.RedirectUrl, true);
    }

    If your web application already contains a form for which the runat attribute has the value server, add the following code to the form where you would like the Google Checkout button to display:

    <cc1:GCheckoutButton id="GCheckoutButton1" onclick="PostCartToGoogle" runat="server" />

    If your web application does not contain a form for which the runat attribute has the value server, add the following code to the form where you would like the Google Checkout button to display. Note: The following code indicates that your application should display a large checkout button; you may alter this setting.

    <form id="Form1" method="post" runat="server">
        <cc1:GCheckoutButton id="GCheckoutButton1" onclick="PostCartToGoogle" Size="Large" runat="server" />
    </form>

    Note: You can change several properties of the Google Checkout button by adding attributes to the code that displays the button. For example, to make the button display on a transparent background, you would add Background="Transparent" to the code that displays the button.

    • The Background property indicates whether the Checkout button should appear against a white or a transparent background. Valid values for this property are White and Transparent.

    • The CartExpirationMinutes property indicates the length of time, in minutes, after which an unsubmitted shopping cart will become invalid. A value of 0 indicates that the shopping cart does not expire.

    • The Currency property identifies the three letter currency code that should be associated with any prices included in generated API requests. You should set this value to USD. (Google Checkout does not yet support any other currencies.)

    • The Size property identifies the size of the Google Checkout button that will appear on your page. You can choose between a small (160x43), medium (168x44) or large (180x46) button. Valid values for this property are Small, Medium and Large.

  5. You will need to choose one of the following options.

    • If you do not already have a web.config file, create one in the root directory of the IIS application. Your web.config file should have the following content.

      <configuration>
      <appSettings>
      <add key="GoogleMerchantID" value="Your Merchant ID" />
      <add key="GoogleMerchantKey" value="Your Merchant Key" />
      <add key="GoogleEnvironment" value="Sandbox" />
      </appSettings>
      </configuration>

    • If you already have a web.config file but that file does not contain an <appSettings> section, add the following code after the <configuration> tag that starts the file.

      <appSettings>
      <add key="GoogleMerchantID" value="Your Merchant ID" />
      <add key="GoogleMerchantKey" value="Your Merchant Key" />
      <add key="GoogleEnvironment" value="Sandbox" />
      </appSettings>

    • If you already have a web.config file and that file contains an <appSettings> section, add this code inside the <appSettings> section.

      <add key="GoogleMerchantID" value="Your Merchant ID" />
      <add key="GoogleMerchantKey" value="Your Merchant Key" />
      <add key="GoogleEnvironment" value="Sandbox" />

    Note: You need to make these changes to the web.config file in your test environment and to the web.config file in your production environment. Each file must specify different values for the GoogleMerchantID, GoogleMerchantKey and GoogleEnvironment keys.

    You can find the merchant ID and merchant key to use in your test environment in your Sandbox account. To locate these values, log in to your Sandbox account, click on the Settings tab and then click on the Integration link in the menu on the left side of the page. In your test environment, the value of the GoogleEnvironment key should be Sandbox.

    You can find the merchant ID and merchant key to use in your production environment in your Google Checkout account. Again, log in to your account, click on the Settings tab and then click on the Integration link in the menu on the left side of the page. In your production environment, the value of the GoogleEnvironment key should be Production.

    The screenshot below shows the location of your merchant ID and merchant key in your Google Checkout account.

  6. Open your page in a web browser.

  7. The Google Checkout button should appear on the page. Click on the button to send a test request. You should be directed to a Google Checkout page that displays an order for two Snickers bars for a total cost of $1.50.

Complex Shopping Cart Example

After successfully testing your installation of the GCheckout module, you may want to test a more advanced example of a Checkout API request. Whereas the original example submits a simple order for two candy bars, the following code submits a more complex order. This order contains two different products. It also contains tax rules for California and Illinois as well as four shipping options. The California Express shipping option is only available in California and Nevada; the UPS Ground shipping option is only available in the continental United States; and the U.S. Postal Service and in-store pickup shipping options do not specify shipping restrictions.

To test this example, locate the following line of code in the Google Checkout button's click handler:

Req.AddItem("Snickers bar", "Packed with peanuts", 0.75m, 2);

Add the following code immediately after this line of code:

Req.AddItem("Gallon of Milk", "Milk goes great with candy bars!", 2.99m, 1);
Req.AddStateTaxRule ("CA", 0.0825, true);
Req.AddStateTaxRule("IL", 0.0625, false);
ShippingRestrictions Only48Lower = new ShippingRestrictions();
Only48Lower.AddAllowedCountryArea(GCheckout.AutoGen.USAreas.CONTINENTAL_48);
Req.AddFlatRateShippingMethod ("UPS Ground", 7.05m, Only48Lower);
ShippingRestrictions OnlyCA_NV = new ShippingRestrictions();
OnlyCA_NV.AddAllowedStateCode("CA");
OnlyCA_NV.AddAllowedStateCode("NV");
Req.AddFlatRateShippingMethod("California Express", 6.35m, OnlyCA_NV);
Req.AddFlatRateShippingMethod ("USPS", 3.08m);
Req.AddPickupShippingMethod("Pick up in store", 0);
Req.ContinueShoppingUrl = "http://www.example.com/continueshopping";
Req.EditCartUrl = "http://www.example.com/editcart";

Start your web application and click the Google Checkout button. You should be directed to a Google Checkout page that displays an order for two Snickers bars and a gallon of milk for a total cost of $4.49.

Note: The following image displays the order confirmation screen for an order being sent to Alaska.

You may want to perform the following tests to better understand how your customer would interact with the Google Checkout system.

  • If you are not already logged in, log in to Google Checkout.

  • Modify your shipping address to see how the shipping address affects the tax charged for the order and the shipping options displayed to the user.

    • Enter a shipping address in California, such as "123 Main Street, Mountain View CA 94043". When you select this as the shipping destination, you should see four shipping options. Since the tax rule in the XML indicates that shipping charges are taxed in California, the tax should adjust as you select different shipping options with different costs.

      • The UPS Ground option should display a cost of $7.05 and, if you select this option, the tax for the order should be $0.95.
      • The California Express shipping option should display a shipping cost of $6.35 and, when this option is selected, the tax for the order should be $0.89.
      • The USPS shipping option should display a shipping cost of $3.08 and, when this option is selected, the tax for the order should be $0.62.
      • The pickup option should not have a charge and, when this option is selected, the tax for the order should be $0.37.

    • Change the shipping address to an address in Nevada, such as "123 Main Street, Las Vegas NV 89101". When you select this as the shipping destination, you should see the same four shipping options as are available in California. However, since there is no tax rule for Nevada, there should be no tax on either the shipping charges or the items in the order.

    • Change the shipping address to an address in Illinois, such as "123 Main Street, Chicago IL 60605". When you select this as the shipping destination, you should see three shipping options. (The California Express option should not be available in Illinois.) In addition, since the tax rule in the XML indicates that shipping is not taxed in Illinois, tax for the order should be $0.28 regardless of the shipping option that is selected.

    • Change the shipping address to an address in Alaska, such as "123 Main Street, Nome AK 99763". When you select this as the shipping destination, you should see two shipping options; only the USPS and in-store pickup options are available in Alaska. In addition, since there is no tax rule for Alaska, there should be no tax on either the shipping charges or the items in the order.

  • Click the Change order link that appears above the price column in your order. The link should direct you to http://www.example.com/editcart. This URL is set by this line in your code:

    Req.EditCartUrl = "http://www.example.com/editcart";

  • Click the Place your order now button that appears beneath your order total and shipping information. The ensuing page will display a link to return to your store. This link should direct you to http://www.example.com/continueshopping. This URL is set by this line in your code:

    Req.ContinueShoppingUrl = "http://www.example.com/continueshopping";

Integrating the Sample Code into your Web Application

This section explains the code changes you will need to make to your web application to implement Google Checkout. The following list identifies the four APIs used in Google Checkout and the types of changes you will need to make to implement each API.

  • Checkout API

    1. Follow the steps in the previous section for installing the GCheckout module. You can use Visual Studio or a text editor to install the GCheckout module.

    2. After successfully testing your installation of the GCheckout module, update the code in the click handler for the Google Checkout button to build a Google Checkout XML API request.

      • Developers who are using Visual Studio will modify the GCheckoutButton1_Click method updated in step 8 of the GCheckout module installation process for Visual Studio.
      • Developers who are using a text editor will modify the PostCartToGoogle method updated in step 4 of the GCheckout module installation process for text editors.

      Remove the following line of code. You will insert other code in its place in the next step.

      Req.AddItem("Snickers", "Packed with peanuts", 0.75m, 2);

    3. Insert calls to the .NET methods in the CheckoutShoppingCartRequest.cs file to create the XML for Checkout API requests. For example, your code should loop through the items in the customer's shopping cart and call the AddItem method for each item.

  • Merchant Calculations API -

    1. Create an .aspx page that will handle merchant-calculation-callback requests from Google Checkout. This page should parse merchant-calculation-callback requests and then call the methods that you use to calculate taxes, shipping charges, and discounts for coupons and gift certificates.

      The classes and methods in the MerchantCalculations directory of the sample code distribution may help you to develop the .aspx page. Please check this document in coming weeks for more detailed instructions about how to call and use these methods.

    2. Use the URL for your .aspx page as the value of the <merchant-calculations-url> element in your Google Checkout API requests. Google Checkout will then send merchant-calculation-callback requests to your .aspx page.

  • Notification API -

    1. Create an .aspx page that will handle notifications, such as order state change notifications, and then send the information in those notifications to the appropriate internal systems.

      Note: The .NET sample code distribution does not include classes or methods to process notifications or to send notification acknowledgments.

    2. Enter the URL for your .aspx page in the API callback URL field in your Google Checkout settings. To locate this field, log in to your checkout account and click the Settings tab. Then click the Integration link in the menu on the left side of the page.

  • Order Processing API

    Modify your existing order tracking system to send Order Processing API requests. The classes and methods in the OrderProcessing and Util directories of the sample code distribution may help you to create the XML for your Order Processing API requests. Please check this document in coming weeks for more detailed instructions about how to call and use these methods.

Understanding the .NET Client Libraries

This section describes the different files included in the Google Checkout sample code for .NET. The base directory for the code contains several classes that are used to create any type of API request or to process any type of API response. It also contains several other files, including the GCheckout.sln file, which could be compiled to a create a new .dll file. Finally, the base directory contains four subdirectories: Checkout, MerchantCalculations, OrderProcessing and Util.

The base directory of the .NET sample code distribution contains the following files:

  • apiv2.cs - This class contains automatically generated methods, based on the Google Checkout XML schema, that are used to generate the XML for API requests.

  • apiv2.xsd - This file contains the version of the Google Checkout XML schema used to generate the methods in the apiv2.cs class. The newest version of this file can be downloaded from http://code.google.com/apis/checkout/apiv2.xsd.

  • AssemblyInfo.cs - Visual Studio reads this file to obtain version information and build options for the project.

  • GCheckout.csproj - This file contains a list of all .cs files that are part of the project. Visual Studio uses this information to know what to compile and which files to display in the Solution Explorer window.

  • GCheckoutRequest.cs - This class contains methods for sending API requests to Google Checkout.

  • GCheckout.sln - If you choose to modify the sample code, you can compile this solution file to create a new .dll file.

  • xsd.bat - This file uses the XML schema stored at apiv2.xsd to generate an updated version of the apiv2.cs class file.

The base directory of the .NET sample code distribution also contains the following subdirectories: