X-Cart:Google Checkout

What Google Checkout module does

Google Checkout is a module that integrates Google Checkout flow with your store website. The integration does not remove the standard X-Cart's checkout method, it just provides an alternative allowing your customers to choose, which of the two checkout methods they wish to use. The store administrator processes the orders created through Google Checkout using X-Cart's 'Google Checkout: Order processing' interface.

Roles in Google Checkout module management

If you are an X-Cart GOLD administrator/provider or an X-Cart PRO administrator:

• You can enable/disable the module Google Checkout (see the section #Enabling Google Checkout Module).
• You can configure the module Google Checkout (see the section #Configuring Google Checkout Module).
• You can control which of the products in the store should be available through Google Checkout (see the section #Disabling Google Checkout for Certain Types of Products).
• You can process orders created through Google Checkout and update their statuses as necessary (see the section #Processing Google Checkout Orders).

If you are an X-Cart PRO provider:

• You can control which of your products should be available through Google Checkout (see the section #Disabling Google Checkout for Certain Types of Products).

How 'Google Checkout' Module Works

Google Checkout is a service that offers Internet users the ability to conveniently and securely buy products from multiple online stores using a single buyer profile. Online merchants that provide their customers the ability to use Google Checkout at their stores use special Google Checkout merchant accounts to accept and process Google Checkout orders.

X-Cart's Google Checkout module integrates Google Checkout service with X-Cart system in such a way that the merchant can process Google Checkout orders directly from the store's Admin area.

To provide Google Checkout service at an X-Cart based store, the merchant needs to set up an account with Google Checkout. The merchant will be able to use this account in two ways. On the one hand, he or she will be able to use this account to log in to the Google Checkout Merchant Center and process orders from there. On the other hand, the merchant will be able to specify his or her Google Checkout account information on the Google Checkout module configuration page in the store's Admin area and thus to enable the store to function in close connection with Google's Merchant Center. In the latter case, the merchant will not have to go the Merchant Center every time he or she needs to check Google Checkout orders, because all the essential information will be available to him or her in X-Cart's Orders Management section.

Google Checkout orders will appear in the Orders list along with orders placed in the traditional X-Cart checkout way. The merchant will instantly be able to identify them as placed through Google Checkout by the look of the drop-down boxes showing their X-Cart statuses: the Status boxes of Google Checkout orders look inactive (grayed out). That is perfectly normal, because, due to the way Google Checkout module functions, the X-Cart statuses of orders created using Google Checkout do not need to be updated manually the way you do it for orders placed using the standard checkout method.

On the whole, processing of Google Checkout orders differs from processing of orders created using X-Cart's standard checkout.

The first thing that needs to be understood is that, although both Google Checkout and X-Cart treat order processing as updating of an order's status, they are entirely different systems and use different terms to describe the process. X-Cart's Google Checkout module combines the two systems in one, so the merchant has to deal with order statuses both in terms of Google Checkout and in terms of X-Cart.

Plainly speaking, every Google Checkout order in an X-Cart based store is characterized by two statuses: its Google Checkout status and its X-Cart status. The Google Checkout status of an order is a reflection of the order's financial and fulfillment state in Google Checkout system. The order's X-Cart status is a reflection of the order's progress in X-Cart. As Google Checkout system plays a primary role in processing of orders created through Google Checkout, an order's X-Cart status is fully dependent on the order's status in Google Checkout system.

The Orders Management section of X-Cart's Admin area provides an interface that allows the merchant to interact with Google Checkout system - a section titled 'Google Checkout: Order processing'. The section is displayed on every Order details page (below the 'Order details' dialog box) and allows the merchant to process the order opened for viewing/modification in terms of Google Checkout. The merchant uses the controls of this section to issue commands to Google Checkout telling Google Checkout what to do with the order (update the order's financial or fulfillment state, add information to the order, etc). When Google Checkout performs a command issued to it by the merchant, it sends X-Cart a notification as to whether the requested action has been performed successfully. X-Cart receives the notification and updates the order's X-Cart status accordingly.

Registered X-Cart customers can track the progress of orders placed through Google Checkout both in X-Cart and in their personal Google Checkout buyer accounts. Anonymous customers can place orders using Google Checkout, but, as they do not have access to the orders history in X-Cart, can track orders only using the Purchase history page in Google Checkout.

For more information on Google Checkout module, study the following chapters.

Google Checkout Order States

At any moment in time any order created using Google Checkout exists in two states:

• financial order state (identifies the financial status of the order),
• fulfillment order state (indicates the status of the order in the order handling process).

The possible financial order states are:

• REVIEWING - The order is being reviewed by Google.
• CHARGEABLE - The order is ready to be charged.
• CHARGING - The order is being charged. The merchant may not refund or cancel an order until the charge is completed.
• CHARGED - The order has been successfully charged.
• PAYMENT_DECLINED - The charge attempt failed.
• CANCELLED - The seller canceled the order. An order's financial state cannot be changed after the order is canceled.
• CANCELLED_BY_GOOGLE - Google canceled the order. If Google cancels an order, the merchant is notified of the reason the order was canceled in the <reason> tag of an order state change notification.

The possible fulfillment order states are:

• NEW - The order has been received but not prepared for shipping.
• PROCESSING - The order is being prepared for shipping.
• DELIVERED - The seller has shipped the order.
• WILL_NOT_DELIVER - The seller will not ship the order. This status is used for canceled orders.

According to Google's system of order states, the states of an order that has just been placed are REVIEWING and NEW. As the order's financial and fulfillment information changes, its Google Checkout states are updated.

In X-Cart, the merchant can see the history of state changes of any order in the Order state log displayed on the Order details page pertaining to that order.

Understanding Google Checkout Flow in X-Cart

When Google Checkout module is enabled and configured, customers shop at the store as usual adding items to the shopping cart. As soon as a customer adds to the cart an item that can be paid for using Google Checkout, two checkout buttons appear on the storefront: one for X-Cart's internal checkout, and one for Google Checkout. The buttons can be seen at the top of any store page (below the page header) and on the cart page (below the list of cart items).

To use Google Checkout, the customer should click the Google Checkout button. After the customer clicks the button, the store forms an encrypted XML Checkout API request to Google Checkout server. This request contains complete information about the customer's shopping cart (a list of product items contained in the shopping cart, information on their prices and quantity, a complete set of taxes that can be applied to the cart with a listing of tax rates and definitions of destination zones to which they should be applied, a list of shipping methods that a customer may use to ship the order, information as to whether any gift certificates or discount coupons can be redeemed when paying for the order, etc). When the customer is redirected to Google Checkout, Google displays a Sign In/Sign Up page from which the customer can sign in to his or her existing Google account or create a new Google account. If the customer has recently been shopping with Google Checkout and has a valid cookie, the Sign In/Sign Up page does not appear, and the customer goes directly to a page where he or she can create an order - the Place Order page.

After the customer signs in, creating a new account if necessary, Google displays the Place Order page. The customer uses the controls of the Place Order page to choose an address to which he or she wishes the order to be shipped and a shipping option. If the customer has a gift certificate or a coupon code that he or she wishes to apply to the order, he or she can enter these codes using a field provided for this purpose on the Place Order page. After the customer selects a shipping address or enters a gift certificate or coupon code, Google forms a merchant-calculation-callback which it sends to the store in the form of an XML request. The data provided by this callback (the list of shipping addresses, shipping methods and codes entered by the customer on the side of Google Checkout) allows the store to calculate the order total amount for every possible combination of a shipping method and a customer address considering the taxes, the cost of shipping and the discount amount that need to be applied. The store then sends the results of the merchant calculations as a merchant-calculation-results response to Google Checkout server. Google Checkout displays the results of merchant calculations on the Place Order page, updating the values dynamically if the customer changes the shipping address or the shipping option to be used.

Note: Google allows three seconds for the store's calculations service to perform any necessary calculations and return a merchant-calculation-results response. If the merchant calculation fails for any reason, or if Google does not receive a response within three seconds, Google uses the backup tax and shipping values.

The customer submits the order by clicking the button Place your order now. Immediately, a new order is created on the side of Google. Google sends the store a new-order-notification. After the notification is received, a new order is created in X-Cart with the status Queued.

Having successfully placed an order, the customer sees a Thank you message from Google and can return to the store. In the store, the customer sees a message confirming order placement and is provided with an invoice for the order. Next, he or she receives an order placement confirmation email from Google Checkout.

The merchant is also notified about the new order by email: one notification is sent to the merchant's Google Checkout account by Google, another one is sent to the Orders department email address by X-Cart (The latter is sent only if the respective notification is enabled in General settings->Email notifications options). The merchant can then access the order in the store's Admin area, review the order details and process it.

Processing of a Google Checkout order typically includes:

• reviewing the order,
• charging the customer,
• adding tracking information to the order,
• shipping and confirming the order.

Upon receiving a new order, Google Checkout assigns to it its first fulfillment status - NEW. (When the merchant begins processing the order, he or she may choose to update this status to PROCESSING by clicking a Process order button in the 'Google Checkout: Order processing' interface; however, this step is optional).

Shortly after the order gets placed, Google Checkout begins reviewing it, which corresponds to the financial status REVIEWING. The most important part of the process of reviewing is payment authorization. Google Checkout authorizes the customer's credit card for the amount of the purchase and, as soon as the payment is authorized, it sends X-Cart an order state change notification confirming that the order can now be charged. The order's financial status is updated to CHARGEABLE.

During the stage of reviewing, Google Checkout also performs some risk checks to prevent fraud and sends X-Cart a risk-information-notification providing the customer's IP, partial credit card number, account age information, AVS, CVN, eligible-for-protection statuses and other data that may help make a decision as to whether the order is fraudulent or not.

Normally, the merchant does not have to review the risk information for every order: he or she can configure X-Cart's Google Checkout module to review the results of the risk checks performed by Google and, according to the results of these checks, either to send Google Checkout a request to charge the order or to put the order off for manual processing by the merchant. A properly configured Google Checkout module will scan all incoming risk information notifications for the customers' AVS, CVN and eligible-for-protection statuses and will check them against the conditions set by the merchant on X-Cart's General settings->Google Checkout options page. If the conditions are satisfied, X-Cart will automatically send a request to Google Checkout to charge the order. If the risk information received from Google does not meet the conditions, the order will remain in the Queued status indefinitely until the merchant chooses to process it manually. In the latter case, if the merchant finds the risks associated with processing the order acceptable, he or she will be able to send a request to Google to charge the order by clicking a Charge order button in the 'Google Checkout: Order processing' interface.

Provided that the order is in the CHARGEABLE state, upon receiving a charge-order request from the store, Google attempts to charge the amount specified in the order to the customer's account. While the order is being charged, its financial state appears in the order details as CHARGING. Once the charge is completed, Google sends the store a charge-amount-notification, and the financial order state is updated to CHARGED. A change of the Google Checkout financial order state to CHARGED induces an automatic update of the order status in X-Cart: in terms of X-Cart order statuses, the order becomes Processed. If, however, Google's effort to authorize or charge a customer's credit card fails, Google puts the order in the PAYMENT_DECLINED state and emails the customer to request a new credit card. If the customer does not provide a new credit card in 72 hours, the order's financial state is updated to CANCELLED_BY_GOOGLE, fulfillment state - to WILL_NOT_DELIVER. When that happens, the status of the order in X-Cart becomes Failed.

As you would expect, orders that get charged successfully are shipped. The merchant can add carrier tracking information to Google Checkout orders, so the customers will be able to track them in their Google Checkout buyer accounts. A tracking number is added to an order as usual (using the 'Tracking number' field in the 'Order details' section) and is associated with the order in Google Checkout system by clicking an Add tracking data button in the 'Google Checkout: Order processing' interface.

Once an order gets shipped, the merchant informs the customer that the order is on its way by updating the fulfillment order state to DELIVERED. The updating is done with a click of a Deliver order button. As a result, the order is marked 'Shipped' in the Merchant Center and on the buyer's account page; a system-generated email is sent to the customer by way of shipping confirmation. After the Google Checkout fulfillment state becomes DELIVERED, the X-Cart status of the order is updated to Completed.

X-Cart's 'Google Checkout: Order processing' interface allows the merchant to post messages to the Google Checkout account of any customer who has placed a Google Checkout order at the store. If necessary, the message posted to a customer's Google Checkout account can be duplicated to the customer's email address.

The module also provides the merchant with the ability to perform order cancellations and refunds.

Order cancellations are done using a Cancel order button provided by the 'Google Checkout: Order processing' interface. The financial state of an order that gets canceled by the merchant is updated to CANCELLED, the fulfillment status - to WILL_NOT_DELIVER. The order automatically becomes Failed in X-Cart. For each order being canceled, the merchant can provide a reason for cancellation and a comment (Both the reason and the comment will be visible in the customer's buyer account and in the Merchant Center after the order status is updated).

Orders that have already been charged need to be refunded before they can be canceled. To issue a refund to a customer, the merchant uses a Refund order button. A refund amount, a reason and a comment can be sent to Google using a simple form provided by the 'Google Checkout: Order processing' interface.

Restrictions Imposed by 'Google Checkout' Module

Google Checkout module imposes some restrictions on X-Cart functionality:

• For compatibility with Google Checkout:
  • taxes may not be included into the product price
  • cart totals may not be displayed with tax included

To meet this restriction, disable the tax options 'Included into the product price', 'Display product price including tax' and 'Display cart/order totals including tax'.

• When sending information about a customer address in the merchant-calculation-callback, Google Checkout passes to the store the customer's country code, state, city and postal code. The address and county fields are not passed. Accordingly, X-Cart cannot identify the customer's destination zone based on address or county masks.

Considering this restriction, you may want to avoid using destination zones based on address or county masks in your store.

• Google Checkout API allows customers to use discount coupons created by the X-Cart administrator. However to redeem a discount coupon, your customers will be supposed to enter its code using a field on Google Checkout's Place Order page. Coupons entered on X-Cart checkout pages will not be used. Merchants in the U.K. cannot yet use the Merchant Calculations API to calculate coupons or gift certificates, for more details please refer to http://code.google.com/apis/checkout/developer/index.html
• Google Checkout does not discriminate between discount coupons and gift certificates: the Place Order page provides a single input field that can be used for both types of codes. As a result, the store itself has to determine, whether the code sent to it in the merchant-calculation-callback request is a gift certificate or a discount coupon. The mechanism that checks the code on the side of the store first matches the code entered by the customer against the discount coupon codes stored in the store database to determine whether the code is a discount coupon, and only if no match is found does it start matching the code against gift certificate codes. This has an important consequence: the codes used for discount coupons and gift certificates should be different, otherwise X-Cart will not be able to discriminate between gift certificates and discount coupons correctly (If the code of some gift certificate happens to be the same as the code of some discount coupon, the system will identify this gift certificate as a discount coupon).
• Using real-time shipping rates calculation in X-Cart increases the risk of X-Cart's not being able to provide a merchant-calculation-results response to Google's merchant-calculation-callback within the allowed period of three seconds. If Google does not receive a response within three seconds, it will use the backup tax and shipping values it received in the Checkout API request. If this represents a problem, disable real-time shipping rates calculation at your store.

Preparing to Use 'Google Checkout'

Setting up a Google Checkout merchant account

To be able to use Google Checkout at your store, you will need a Google Checkout merchant account. If you have not yet signed up for one, you can do so at at this page. Sign in to your merchant account to obtain your Merchant ID and Merchant Key. These values will be used by your store to encode order information before it is submitted to Google Checkout. You will need to specify both of these values on the General settings/Modules options->Google Checkout options page (Make sure you use these values only in Live mode. For Test mode, the Merchant ID/Merchant Key pair needs to be obtained separately. See the section Setting up test accounts in Google Checkout Sandbox service further in this chapter). In your merchant account, your Merchant ID is located on the 'Settings' tab under 'Primary contact information' header, Merchant Key - in the 'Integration' section ('Settings' tab->'Integration') under 'Account information' header.

Setting up test accounts in Google Checkout Sandbox service

If you wish to experiment with Google Checkout before offering the service to your customers, create two test accounts in the Sandbox. The Sandbox is a development system that is designed to help you test your Google Checkout implementation. One of your Sandbox accounts needs to function as a customer account and the other needs to function as your merchant account.

A Sandbox customer account can be created at https://sandbox.google.com/checkout, a Sandbox merchant account - at https://sandbox.google.com/checkout/sell.

Sign in to your test merchant account to locate your Merchant ID and Merchant Key for Test mode. You will need to specify these values on the General settings/Modules options->Google Checkout options page when running your Google Checkout module in Test mode. In your merchant account, both your Merchant ID and your Merchant Key are listed in the 'Integration' section ('Settings' tab->'Integration') under the 'Account information' header.

Adjusting the settings that will enable your store to accept callbacks from Google Checkout

When processing orders, Google Checkout and X-Cart exchange data in the form of various notifications and messages. To enable your store to receive notifications and other callbacks from Google, you need to set up the settings as described below.

Google Checkout merchant account's settings

In your Google Checkout merchant account ('Settings' tab->'Integration'):

• API callback URL: https://www.yoursite.com/xcart/payment/ps_gcheckout.php (this is an example URL)
• Callback contents: Notification as XML
• API Version: Version 2.0

Basically, you should configure "Callback contents" and "API Version" settings properly (as suggested above) and provide Google with an HTTPS API callback URL (an HTTP URL may be used for Test mode), which is entered into the corresponding field.

API callback URL tells Google Checkout where to send notifications about new orders, order state changes, and other events. The URL that you need to specify needs to point to the script payment/ps_gcheckout.php.

Note: A URL pointing to the location of the payment/ps_gcheckout.php script in your store is provided on the General settings/Modules options->Google Checkout options page in the Admin area.

Note: Your API callback URL needs to be secured by SSL v3 or TLS using a valid certificate from a major Certifying Authority. Please note that the certificate being used needs to be signed: Google Checkout does not trust unsigned (or self-signed) certificates. If the certificate used at your site is not signed (or self-signed), your store will not be able to receive any messages or notifications from Google Checkout, so the module will not be able to function correctly.

HTTP Basic Authentication for payment/ps_gcheckout.php

Please also note that, for Live mode, you need to provide HTTP basic authentication for access to the script payment/ps_gcheckout.php. According to http://code.google.com/apis/checkout/developer/index.html#security_precautions it only accepts messages that are authenticated by HTTP Basic Authentication, using your Merchant ID and Merchant Key as the username and password.

If PHP on your server runs in CGI mode, in order to ensure that Google Checkout module can accept callback requests from the Google Checkout server, make sure mod_rewrite is installed and .htaccess file in the payment/ directory contains the following lines:

<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule .* - [E=REMOTE_USER:%{HTTP:Authorization},L]
</IfModule>

If this does not help, or if mod_rewrite is not installed on the server, you can choose to disable the built-in HTTP authentication routine in the callback script. To do so, uncomment the line:

define('GCHECKOUT_IGNORE_AUTH', 1);

in the modules/Google_Checkout/init.php file.

Warning! Please only uncomment this line if your callback script is protected by HTTP authentication via the server configuration (for example via .htaccess file).

Basically, to provide HTTP basic authentication via the server configuration, you need to set up .htaccess file in the payment/ directory in order to protect access to the ps_gcheckout.php file with the username = "Your Merchant ID" and the password = "Your Merchant Key".

For example, if your Merchant ID is "abc123" and Merchant Key password "123", then the password protection can be done as follows:

1. Open the Summary page of the X-Cart Admin area by selecting Tools -> Summary on the Admin menu.

2. In the Environment info section, find and copy the X-Cart directory path (something like /home/user/www/xcart). You will need it a bit later.

3. If you have shell access to your hosting server, enter the following command:

htpasswd -c .htpasswd abc123

and then press Enter. Now enter the merchant key (password) two times.

4. Copy the .htpasswd file to the X-Cart's payment directory.

5. Open payment/.htaccess and paste the following data to it:

<Files "ps_gcheckout.php">
AuthType Basic
AuthName "Google Checkout"
# In the line below, replace /home/user/www/xcart/ with the actual X-Cart path shown on your Admin summary page.
AuthUserFile /home/user/www/xcart/payment/.htpasswd
require valid-user
</Files>

Alternatively, you can password-protect the payment/ps_gcheckout.php file using the password protection setup facility in the control panel of your hosting account.

Enabling Google Checkout module

To enable the module:

1. Go to Administration menu->Modules.
2. In the list of modules, find the name of the module - Google Checkout - and select the check box next to it.
3. Click Update.

The module is enabled. You should see a link Configure to the right of the module description. This link can be used to access the General settings/Modules options->Google Checkout options page where the module can be configured.

Configuring Google Checkout module

After enabling the module, you need to adjust its configuration. This can be done using the General settings/Modules options->Google Checkout options page:

You need to complete the fields on the Google Checkout options page as follows:

1. Set your account options:

• Merchant ID: Enter your Merchant ID (a unique numeric code assigned to your business by Google).
• Merchant key: Enter your Merchant key (a unique alphanumeric code that helps secure your communications with Google). Both your store and Google will use this key to authenticate and verify the integrity of any messages they exchange.
• Test/Live mode: Select whether you wish to use your Sandbox account (test mode) or actual Google Checkout account (live mode). The Sandbox works just like the production version of Google Checkout, except that test credit card numbers are allowed, and no funds are ever taken from or paid to anyone.
• Seller account currency: Specify the type of currency supported by your seller account. Your X-Cart store will send prices to Google Checkout in this currency (There is no currency converter, so it is expected that your store uses the same currency). At present, Google Checkout supports only two types of currency - Pounds Sterling (GBP) and United States Dollar (USD).

IMPORTANT: The Merchant ID and Merchant key that need to be entered for Test and Live modes are different!

2. Set up the conditions on which orders should be charged:

• Charge order if the result of AVS check-up is: Full AVS match (address and postal code) / Partial AVS match (postal code only) / Partial AVS match (address only) / No AVS match / AVS not supported by issuer. Select the AVS status (or statuses) on which the system should charge the order. To select multiple statuses, hold down the Ctrl key while clicking on the appropriate status names with your mouse.
• Charge order if the result of CVN check-up is: CVN match / No CVN match / CVN not available / CVN error. Select the CVN status (or statuses) on which the system should charge the order. To select multiple statuses, hold down the Ctrl key while clicking on the appropriate status names with your mouse.
• Charge order only if it is eligible for Google Checkout's payment guarantee policy: Select this check box if you wish the system to charge only the orders that are eligible for Google Checkout's payment guarantee policy.

3. Adjust the options in the section 'Other options':

• Cancel order if merchant calculations fail: Select this check box if you wish Google Checkout to cancel orders for which it does not receive the correct results of merchant calculations in response to merchant-calculation-callback. Google may fail to receive the said results if, for example, the XML being sent to Google Checkout contains errors or if the response time of your server to Google's merchant-calculation-callback exceeds 3 seconds because of high server load or the server being unstable. If you leave the check box 'Cancel order if merchant calculations fail' unselected, Google Checkout will use the default values it has gotten from X-Cart - the 'Default shipping cost' (may be specified further in the section 'Other options'), the backup tax rate that has been sent to Google Checkout with the shopping cart, etc.
• Disable notifications to customers about placed orders: Specify whether you wish order placement notifications from X-Cart to be sent to customers placing orders through Google Checkout.

IMPORTANT: Google Checkout program policy discourages use of order confirmation emails by merchants in order to reduce the number of redundant emails sent to customers. Because Google itself sends the necessary confirmations, X-Cart's order placement notifications to customers are disabled by default and are not sent unless you re-enable them. We strongly recommend you keep the check box for the option 'Disable notifications to customers about placed orders' selected.

• Default shipping cost (will be used if Google Checkout does not receive a correct XML response from your store): Specify a shipping cost that you wish to be sent to Google Checkout if, for some reason, your store cannot provide Google Checkout with a shipping cost value calculated based on the customer's shipping address (For example, if the XML being sent to Google Checkout contains errors or if the response time of your server to Google's merchant-calculation-callback exceeds 3 seconds because of high server load or the server being unstable).
• Display a note about products not available through Google Checkout in the cart: Select this check box if you wish a note "Sorry, this product is not available through Google Checkout" to be displayed on the cart page next to the title of each product not available through Google Checkout.

Note: According to http://checkout.google.com/seller/content_policies.html, certain types of products cannot be sold through Google Checkout. If your store sells such products, you will need to disable Google Checkout for each of them using a special check box on the Product details page. If a customer adds a product for which Google Checkout is disabled to the shopping cart, checkout through Google becomes unavailable for the entire cart (the Google Checkout button becomes inactive). The option 'Display a note about products not available through Google Checkout in the cart' determines whether you let the customer know why this happened or just disable Google Checkout without explanation.

Meeting Google Checkout restrictions

To ensure seamless integration of Google Checkout with your store, X-Cart's Google Checkout module imposes some restrictions on the store configuration. To make sure the configuration of your store meets these restrictions, go to the General settings/Modules options->Google Checkout options page. Any serious issues that might prevent the module from functioning correctly will be displayed in the section 'Issues found' (Please note that this section appears on the page only when there are problems). If you see any errors listed in this section, make changes to the configuration of your store as appropriate. The error messages should disappear.

For more information on Google Checkout restrictions, see the chapter Restrictions Imposed by 'Google Checkout' Module.

Disabling Google Checkout for Certain Types of Products

Google Checkout cannot be used for certain types of products (see http://checkout.google.com/seller/content_policies.html for details). If your store sells products that do not comply with Google Checkout content policies, you should disable Google Checkout for these products.

To disable Google Checkout for a product:

1. Open the product's 'Product details' page.
2. Unselect the check box 'Enable Google Checkout for this product'.

Note: The check box 'Enable Google Checkout for this product' is displayed only when the module Google Checkout is enabled and functions correctly.

1. Click the Save button.

To disable Google Checkout for more than one product, use the Group product editing feature.

Using Google Checkout Integration Issues Console

Google Checkout Merchant Center includes an Integration Issues console that identifies the errors and warnings from the API requests that you have sent to Google Checkout. Errors and warnings appear in the console as they occur, enabling you to debug errors as they occur. The console will display error and warning messages from the previous seven-day period. If there are more than 1000 errors and warnings from the previous seven days, only the most recent 1000 messages will be accessible.

We recommend you check the console periodically to ensure that your Google Checkout integration is working as you expect.

To locate the Integration Issues console, log in to your Merchant Center account and click the 'Settings' tab. Then click the 'Integration' link in the menu on the left side of the page. The console 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.

More information about the Integration Issues Console is available at http://code.google.com/apis/checkout/developer/index.html#integration_issues_console].

Processing Google Checkout Orders

Processing of Google Checkout orders is performed using the 'Google Checkout: Order processing' interface. This interface can be accessed through the 'Order details' page: all you need to do is open a Google Checkout order for viewing/modification and scroll down to the lower part of the page. The 'Google Checkout: Order processing' section is located just below the 'Order details' section. It provides information about the order currently displayed and allows you to perform various operations affecting the order's financial and fulfillment states in Google Checkout.

The upper part of the 'Google Checkout: Order processing' section provides the most essential information about the order like so:

Google Checkout Order: #622748452041546

Total amount: $83.90

Current state:

Fulfillment state: NEW (2006/11/15 08:11:00)

Financial state: CHARGEABLE (2006/11/15 08:11:01)

Below the information about the order's Google order number, total amount and current state, an Order state log box is displayed. The Order state log provides a complete history of order state changes of the order like this:

[2006/11/15 08:11:00] Fulfillment state: NEW

[2006/11/15 08:11:00] Financial state: REVIEWING

[2006/11/15 08:11:01] Financial state changed from REVIEWING to CHARGEABLE

[2006/11/15 08:11:02] RISK INFO received

The information in the Order state log will be updated as you process the order by issuing Google Checkout financial and fulfillment commands.

Below is a complete list of Google Checkout commands that can be issued using the controls of the 'Google Checkout: Order processing' section.

Financial commands

Charge order

The 'Charge order' subsection of the 'Google Checkout: Order processing' section allows the merchant to manually charge the order. Manual charging may be performed within 72 hours after the order has been assigned the status CHARGEABLE.

To perform a charge, click the Charge order button.

The store will send a request to Google Checkout to charge the order. You should see a confirmation in an Information box.

When Google Checkout begins charging the order, the order's financial state will appear in the Order state log as CHARGING. Once the charge is completed, the financial order state will become CHARGED. The status of the order in X-Cart will be updated toProcessed.

If Google's attempt to charge the customer's credit card is unsuccessful, Google will put the order in the PAYMENT_DECLINED state and will send the customer an email message to request a new credit card. If the customer does not provide a new credit card in 72 hours, the order's financial state will be updated to CANCELLED_BY_GOOGLE, fulfillment state - to WILL_NOT_DELIVER. If that happens, the status of the order in X-Cart will become Failed.

Cancel order

The 'Cancel order' subsection allows the merchant to cancel the order. This section is available only when the financial order state is REVIEWING or CHARGEABLE. It does not appear while the order is in the CHARGING or CHARGED state.

Note: If you wish to cancel an order that has already been charged, you first need to refund the order. The section 'Cancel order' will become available after the order becomes REFUNDED.

To cancel the order:

1. Use the 'Reason' drop-down box to select a reason for the cancellation.
2. If necessary, provide a comment in the 'Comment' field.
3. Click the Cancel order button.

The store will send a request to Google Checkout to cancel the order. You should see a confirmation in an Information box.

After Google Checkout cancels the order, the order will be marked CANCELLED in the Google Checkout Merchant Center. A notification will be sent to the customer containing the reason and the comment that you provided.

In X-Cart, the Order state log will show the order's Google Checkout financial state updated to CANCELLED. The X-Cart status of the order will be updated to Failed.

Note: You will not be able to change the order's financial state after the order is canceled.

Refund order

The 'Refund order' subsection allows the merchant to refund the order. Note that this section becomes available only after the order has been charged and is in the CHARGED financial order state.

To issue a refund:

1. Specify the amount that needs to be refunded in the 'Refund amount' field (Partial refunds supported).
2. Provide a reason in the 'Reason' field.
3. If necessary, provide a comment in the 'Comment' field.
4. Click the Refund order button.

The store will send a request to Google Checkout to refund the order. You should see a confirmation in an Information box.

After Google Checkout performs the refund, the order will be marked REFUNDED in the Google Checkout Merchant Center. A notification will be sent to the customer containing the refund reason and the comment that you provided.

In X-Cart, the Order state log will show the order's Google Checkout financial state updated to REFUNDED. The refund amount will be displayed in brackets after the word REFUNDED. Please note that if you perform several partial refunds, you will get a separate REFUNDED record for each of the refunds in your Order state log.

Note: The 'Refund order' command will not affect the X-Cart status of the order in your store. If you wish the order state change caused by the refund to take effect on the side of the store, you need to edit the order manually using X-AOM (Advanced Order Management) add-on module.

Fulfillment commands

Process order

After an order gets placed, it is assigned its first fulfillment status - NEW. When the merchant begins processing the order, he or she may wish to mark the order as being processed (This step is completely optional).

To mark the order as being processed, click the Process order button in the 'Process order' subsection. The order's fulfillment state will be updated to PROCESSING.

Note: The 'Process order' command does not affect the order's X-Cart status.

Add tracking data

The merchant can add carrier tracking information to the order so the customer will be able to track the order via his or her Google Checkout buyer account.

When you ship the order, you assign a carrier tracking number to it using the 'Tracking number' field in the 'Order details' section. To associate this tracking number with the order, click the Add tracking data button. You should see a confirmation message.

Note: The 'Add tracking data' button looks inactive if the order does not have a tracking number. It will be activated after you enter the tracking number into the appropriate field of the 'Order details' section and click the 'Update' button.

Deliver order

Once the order has been shipped, the merchant can inform the customer that the order is on its way. To do so, the merchant can send a system-generated shipping confirmation message to the customer's Google Checkout buyer account and, optionally, to the customer's email address.

To send a shipping confirmation to the customer's buyer account, click the Deliver order button. You should see a confirmation message.

If you also wish to send the shipping confirmation by email, be sure to select the 'Send email to the customer' check box before clicking on Deliver order.

After the shipping confirmation is sent, the order's fulfillment state will be updated to DELIVERED. The X-Cart status of the order will change to Completed.

The order will be marked 'Shipped' in the Merchant Center and on the buyer's account page.

Sending messages

The 'Send message' subsection allows the merchant to send messages to the customer who placed the order. It contains a 'Message' text area, a 'Send email to the customer' check box and a Send message button.

To post a message to the customer's Google Checkout buyer account:

1. Enter the text of the message into the 'Message' text area.
2. Click the Send message button.

The message will be posted. You should see a confirmation message in an Information box.

If, in addition to posting the message to the customer's buyer account, you also wish to send the same message to the customer's email address, select the 'Send email to the customer' check box before clicking the Send message button.

Note: The 'Send message' command does not impact the order's fulfillment state.

Archiving commands

The module provides the merchant with an archiving feature that allows the merchant to manage the list of orders in his or her Merchant Center inbox by moving orders to and from the Merchant Center archive.

When you are finished with an order, you can remove it from the list of orders that appear on the Orders page of the Merchant Center: simply click the Archive order button in the 'Archiving commands' subsection. The order will be archived. You should see an Information box with a confirmation message.

Note: Archiving Google Checkout orders is optional; you may choose not to archive orders.

To restore an order from the archive, click the Unarchive order button. Again, a confirmation message will be displayed in an Information box.

Troubleshooting

I get orders with empty first/last names on them

To receive first and last names in notifications, you must set a preference in your Google Checkout merchant account. To set this preference, log in to your merchant account and click the Settings tab. Then click the Integration link on the left side of the page. Expand the list of advanced settings and check the box next to the setting that says, "Provide the first name, last name and full name of the buyer and order recipient in separate fields in the new order notification." Then click the Save button to update your settings.

FAQ

What API version is supported by Google Checkout module?

Version 2.2