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 chapter #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%23coupons_and_discounts
• 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.