Google Checkout PHP Sample Code

Google Checkout's sample code for PHP is distributed as a .zip file. This file contains a PHP 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-php-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 PHP code libraries and sample implementations. If you are developing a PHP Google Checkout implementation, you can use this documentation as a reference when integrating Google Checkout functionality into your web site.

Requirements for Using PHP Sample Code

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

PHP v4.3.0 or later
libcurl v7.9.0 or later. libcurl is an implementation of CURL, which allows you to send XML over HTTPS using server-to-server HTTP POST requests. Learn more about libcurl at http://us2.php.net/curl/.
libxml-2.4.14 or later. libxml installs a DOM XML library that is used to construct and parse XML messages. Learn more about libxml at http://us2.php.net/manual/en/ref.domxml.php.

Note: This DOM XML library runs on PHP 4, but not on PHP 5. So, to run this sample code, you must be running a PHP version of 4.2.3 or later but not PHP 5 or greater. We do not yet have sample code for PHP 5 using a DOM library.

Understanding the PHP Client Libraries

The checkout-php-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.php library contains functions that are used to communicate with multiple Google Checkout APIs.
The ResponseHandlerAPIFunctions.php 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.php library contains functions for systematically building XML documents that can be included in Google Checkout Checkout API requests.
The MerchantCalculationsAPIFunctions.php 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.php 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.php 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.

Sample API Implementations

CheckoutShoppingCartDemo.php 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.php 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.php 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.php 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.

Additional Files

Several other files are included in the checkout-php-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.php - 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.php, paste an XML request into the text window window or use the Browse and Load XML buttons to load a local XML file.
DebuggingTool.php 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.php 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.
googleCheckout.css contains a stylesheet used by several of the sample implementations.

Integrating the Sample Code into your Web Application

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.php and NotificationAPIFunctions.php 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.

function GetTaxRate($dom_merchant_calculation_callback_obj, $address_id) {
    /*
     * +++ CHANGE ME +++
     * You need to modify this function to contact your internal system that
     * calculates tax. The function should return the tax value calculated by
     * that system.
     */

    return "17.55";
}

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

Mandatory Code Changes

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

Update the return value of the GetMerchantID function in the GlobalAPIFunctions.php file.
Update the return value of the GetMerchantKey function in the GlobalAPIFunctions.php file.

Optional Code Changes

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.php file.

The $GLOBALS["currency"] variable sets a default currency that is used in several places throughout the Google Checkout PHP 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).
The $GLOBALS["logfile"] 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.
The $GLOBALS["error_report_type"] variable identifies the type of error reporting used throughout the sample code. There are three valid values for this variable:
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.
The $GLOBALS["error_logfile"] identifies a file location where Google Checkout error messages will be logged. You may want to update the file name and directory location of this log file.