Google Checkout's sample code for ASP is distributed as a .zip file. This file contains an ASP reference implementation that you can use to integrate Google Checkout on your site. It also contains sample Google Checkout implementations that use those libraries.

The libraries and sample implementations in the checkout-asp-samplecode.zip file correspond to the different Google Checkout APIs. As such, you may be able to disregard certain code libraries or sample implementations if you are not using the APIs that those files implement.

This page provides an overview of the Google Checkout ASP code libraries and sample implementations. It also discusses the GCrypt COM object, which performs base64 encoding and HMAC-SHA1 signature generation. If you are developing a ASP Google Checkout implementation, you can use this documentation as a reference when integrating Google Checkout functionality into your web site.

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

• GCrypt.g_crypt.2. This ActiveX COM object, which is used to encode strings and generate HMAC-SHA1 signatures, is included in the sample code distribution. The COM library has been packaged as a .MSI file and will automatically install into the Windows Component Services COM+ packages on your Windows Server. You will see this package listed as GCrypt.

• Msxml2.DOMDocument.3.0. This object is used to construct and parse XML messages throughout the sample code. Learn more about this object at http://windowssdk.msdn.microsoft.com/en-us/library/ms756987.aspx.

• Msxml2.ServerXMLHTTP.3.0. This object is used to send XML over HTTPS. Learn more about the ServerXMLHTTP at http://support.microsoft.com/kb/290761/EN-US/.

• Scripting.FileSystemObject. This object is used to log messages to a local file. Learn more about this object at http://msdn.microsoft.com.

The checkout-asp-samplecode.zip file includes the following libraries. Note: The first three libraries in the list are used in all Google Checkout implementations. The remaining libraries in the list are only relevant to particular APIs.

This page provides a short description of each code library and a link to more complete documentation of the library. The complete documentation includes a list of all of the functions in the library as well as an explanation of each function, a list of the function's parameters and the function's code.

• The GlobalAPIFunctions.asp library contains functions that are used to communicate with multiple Google Checkout APIs.

• The ResponseHandlerAPIFunctions.asp library contains functions that handle synchronous responses that Google Checkout sends in response to your API requests. For example, when you send a checkout API request, Google Checkout sends a synchronous response that indicates whether your request was received successfully. Note: Synchronous responses do not indicate whether a well-formed request was successfully processed.

  This library contains some code that is only relevant to partners who are implementing either the Merchant Calculations API or the Notification API. This code is identified in comments in the code so that it can be easily removed if it is not needed in your application.

• The CheckoutAPIFunctions.asp library contains functions for systematically building XML documents that can be included in Google Checkout Checkout API requests.

• The MerchantCalculationsAPIFunctions.asp library contains functions that can be used to build responses to Merchant Calculations API requests that Google Checkout sends to your application. These notifications are defined in the Merchant Calculations API documentation.

  Note: This library is only used in Google Checkout implementations of the Merchant Calculations API.

• The NotificationAPIFunctions.asp library contains functions that can be used to systematically handle asynchronous notifications that Google Checkout sends you to update the status of your orders. These notifications are defined in the Notification API documentation.

  Note: This library is only used in Google Checkout implementations of the Notification API.

• The OrderProcessingAPIFunctions.asp library contains functions for systematically building XML documents for Google Checkout Order Processing API requests. Order processing requests are used to update the financial-order-state or the fulfillment-order-state for an order. These requests are defined in the Order Processing API documentation.

  Note: This library is only used in Google Checkout implementations of the Order Processing API.

The Google Checkout sample code for ASP includes a COM object that performs base64 encoding and calculates the HMAC-SHA1 signatures required to submit orders to Google Checkout. You may install the Google Checkout COM object using the GCryptInstaller.MSI file or you can write your own object to perform these functions.

See instructions for installing the Google Checkout COM object. These instructions are also included in the sample code distribution in the install.txt file.

• CheckoutShoppingCartDemo.asp is a simple application that demonstrates how you would send orders to Google Checkout using the Checkout API. This application performs the following operations:

  1. It creates an XML structure containing information about an order.

  2. It generates an encrypted version of the XML created in step 1. The encrypted signature is a cryptographically secure HMAC-SHA1 value in binary format.

  3. It base64 encodes both the order XML and the HMAC-SHA1 value.

  4. It performs a server-side Checkout API request to confirm that the XML in the shopping cart is valid. If the XML is invalid, the application allows you to edit the XML in a text window. Note: This functionality is provided so that you can easily determine whether your store creates valid Checkout API requests if you use the sample code to integrate your online store with Google Checkout.

  5. It embeds the order information and the signature in a form that displays a Google Checkout button. The form submits to the Google Checkout Sandbox test environment. By clicking on the button, you will send the order information to Google Checkout in an HTTP POST request. Google Checkout will then display the order information as it would display to your customer.

  These steps are described in the Processing an Order sections of the Google Checkout Developer's Guide.

• CheckoutShoppingCartDemoAlternativeMethod.asp is a simple application that demonstrates how you would send server-to-server Checkout API requests to Google Checkout. This application displays a simple form that submits an HTTP POST request to itself.

  When the form receives a POST request, it performs the following operations:

  1. It generates an XML structure containing information about an order.

  2. It creates a request that uses HTTP Basic Authentication with your merchant ID and merchant key.

  3. It submits a server-to-server Checkout API request and captures the <checkout-redirect> response returned by Google Checkout.

  4. It extracts the <redirect-url> from the response and redirects the user's browser to that URL.

• OrderProcessingDemo.asp is a simple application that demonstrates how you would update an order's financial order state or its fulfillment order state using the Order Processing API.

• ResponseHandler.asp is a page that handles any type of API request or response that Google Checkout sends to you. This application is designed to receive synchronous responses to your API requests. It also handles asynchronous requests such as those described in the Merchant Calculations API and the Notification API.

Several other files are included in the checkout-asp-samplecode.zip file. The following list identifies those files and offers a short description of each file. It is unlikely that you will need to update any of these files or incorporate their code into your storefront.

• DebuggingTool.asp - is an application that provides an interface for editing an XML document as well as several utilities for validating or sending an API request. To use DebuggingTool.asp, paste an XML request into the text window window.

  DebuggingTool.asp offers the following XML validation and submission options:

  1. The Validate XML button will send your request to the Google Checkout diagnostic server. If the XML is valid, the page will update to display a message indicating that your XML is valid. If the XML is invalid, the page will display a message indicating that the XML is invalid along with a message identifying the error that the diagnostic server located.

  2. The Send Order Processing Command button will send your request to the Google Checkout sandbox server. If you click this button, the command will be sent to Google Checkout's test environment and executed in that environment. The DebuggingTool.asp page will then update to display the synchronous response that Google Checkout sent to your request.

  3. The Display HTML form for Checkout button is used to test Checkout API requests. To use this option, enter the XML for a Checkout API request in the display window and click the Display HTML form for Checkout button. You will then be sent to a page that contains an HTML form that submits your XML request to Google Checkout. This form is similar to the one you would need to include in your online store.

  4. The Submit Cart to Google Checkout button is also used for Checkout API requests. When you use this option, your XML request will be submitted directly to Google Checkout. The next page that displays will be a Google Checkout interface similar to the one your customers will see when they use the Google Checkout option on your site.

• The GCryptInstaller.MSI file installs a COM object used for encoding and HMAC-SHA1 signature generation. See instructions for installing the COM object.

• The GCryptInstallationTest.asp page tests your installation of the GCrypt COM object.

• googleCheckout.css contains a stylesheet used by several of the sample implementations.

If you decide to use this sample code in your web application, you will need to make several code changes or the code will not function. You may also want to make several other code changes affecting logging and reporting. These sets of changes are identified in the following subsections. In addition, there are several functions in the MerchantCalculationsAPIFunctions.asp and NotificationAPIFunctions.asp files that need to be integrated with your internal systems.

When integrating either the code libraries or the sample implementations, please search for the text "+++ CHANGE ME +++" to identify areas in the code that you need to modify. This text will appear in comments with instructions explaining the modifications you need to make. See the following code snippet for an example.

Note: This sample code sends all request to the Google Checkout sandbox server (https://sandbox.google.com/checkout). Your development environment should also send requests to that server. However, your production servers must send requests to the Google Checkout production server (https://checkout.google.com).

The following code changes are necessary or your sample code will not function:

1. Update the return value of the getMerchantId function in the GlobalAPIFunctions.asp file.

2. Update the return value of the getMerchantKey function in the GlobalAPIFunctions.asp file.

You may also want to change the following variables in the sample code. These variables are all set in the setGlobalVariables function in the GlobalAPIFunctions.asp file.

1. The attrCurrency variable sets a default currency that is used in several places throughout the Google Checkout ASP libraries. If your store only sells products in a single currency other than U.S. dollars, you should update this variable's value to contain the appropriate three-letter ISO 4217 currency code. If you sell products in multiple currencies, you will need to implement a function (or other solution) that sets the appropriate currency for each user. Note: The only currency that Google Checkout supports at this time is U.S. dollars (USD).

2. The logFilename variable identifies a file location where Google Checkout messages and API responses will be logged. You may want to update the file name and directory location of this log file.

3. The errorReportType variable identifies the type of error reporting used throughout the sample code. There are three valid values for this variable:

   • 1 - Error messages are logged in the error log file.
   • 2 - Error messages are displayed in the browser.
   • 3 - Error messages are logged in the error log file and displayed in the browser.

   The value in the sample code is 3. Note: You must update this value before releasing this code in production to prevent error messages from displaying in the user's browser.