LiteCommerce:GoogleCheckout

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.

LiteCommerce Google Checkout add-on module integrates Google Checkout service with LiteCommerce system in such a way that the merchant can process Google Checkout orders directly from the store's administration back-end.

How 'Google Checkout' module works

To provide Google Checkout service at an LiteCommerce-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 administration back-end 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 to 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 LiteCommerce Orders Management section.

Google Checkout orders will appear in the Orders list along with orders placed in the traditional LiteCommerce checkout way. On the whole, processing of Google Checkout orders differs from processing of orders created using standard LiteCommerce checkout.

The first thing that needs to be understood is that, although both Google Checkout and LiteCommerce treat order processing as updating of an order's status, they are entirely different systems and use different terms to describe the process. LiteCommerce 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 LiteCommerce.

Plainly speaking, every Google Checkout order in a LiteCommerce-based store is characterized by two statuses: its Google Checkout status and its LiteCommerce 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 LiteCommerce status is a reflection of the order's progress in LiteCommerce. As Google Checkout system plays a primary role in processing of orders created through Google Checkout, an order's LiteCommerce status is fully dependent on the order's status in Google Checkout system.

The Orders Management section of LiteCommerce admin menu provides an interface that allows the merchant to interact with Google Checkout system - a section titled 'Google Checkout'. The section is displayed on every 'Order details' page 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 LiteCommerce a notification as to whether the requested action has been performed successfully. LiteCommerce receives the notification and updates the order's LiteCommerce status accordingly.

Registered LiteCommerce customers can track the progress of orders placed through Google Checkout both in LiteCommerce 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 LiteCommerce, 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 - A description of the system of order states in Google Checkout.
• Google Checkout restrictions - A list of restrictions imposed by 'Google Checkout' module.
• Preparing to Use 'Google Checkout' - Information on how Google Checkout module can be enabled and configured.
• Processing Google Checkout orders - Instructions on how specific Google Checkout commands can be issued using the Google Checkout: Order processing' interface.

Preparing to use Google Checkout

The following steps are necessary to begin accepting orders using Google Checkout:

1. Set up a Google Checkout merchant account;
2. Provide Google with your API callback URL;
3. Configure the module.

Google Checkout restrictions

Google Checkout module imposes some restrictions on LiteCommerce functionality:

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

The coupons created directly in Google Checkout cannot be applied to the orders placed to a LiteCommerce-based store. Such coupon codes are not in the store database and will be ignored.

• Using real-time shipping rates calculation in LiteCommerce increases the risk of LC'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 default shipping cost it received in the Checkout API request. If this represents a problem, disable real-time shipping rates calculation at your store.
• To redeem a discount coupon, your customers will be supposed to enter its code using a field either in LiteCommerce or on Google Checkout's Place Order page. However if a customer decides to use another discount coupon after having entered it in LiteCommerce and gone to Google Checkout, he or she will need to return to your store, delete the coupon, apply another one and go to Google Checkout once again.

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.

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.

Sign in to your test merchant account at https://sandbox.google.com/sell to locate your Merchant ID and Merchant Key for Test mode. You will need to specify these values on the module configuration page of the admin menu 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.

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 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 in the admin menu on the Google Checkout module configuration 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' 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.

Providing Google with your API callback URL

When processing orders, Google Checkout and LiteCommerce 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 provide Google with an HTTPS API callback URL (an HTTP URL may be used for Test mode). An API callback URL tells Google Checkout where to send notifications about new orders, order state changes, and other events. Your API callback URL needs to be entered into the field 'API callback URL' in your Google Checkout merchant account ('Settings' tab->'Integration'). The URL that you need to specify can be found on the Google Checkout module configuration page. Click the Additional information >>> link at the top of the page and locate the URL after the words: This URL should be used as an 'API callback URL' in your Google Checkout account.

The 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 certificates, so if the certificate used at your site is not 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.

In addition to your API callback URL, you need to specify the callback method for your store ('Settings' tab->'Integration' in your Google Checkout merchant account). Google Checkout supports two methods: XML and HTML (name/value pairs). LiteCommerce expects callbacks to be in XML format, so you need to select XML.

Please also note that, for Live mode, you need to provide HTTP authentication for access to the API callback URL. See http://code.google.com/apis/checkout/developer/index.html#security_precautions for details.

The example .htaccess file bundled with LiteCommerce Google Checkout module includes the following lines which need to be uncommented and edited for correct module operation:

DirectoryIndex index.php
<br/>
#<files "callback.php">
#AuthType Basic
#AuthName "Authentication required"
#AuthUserFile /u/<your home folder>/.users
#Require user <your merchant ID>
#</files>

Important!

Please note that this file is only an example and might differ depending on your web server configuration. Do not edit it unless you are sure what you are doing!

Testing your API callback URL

To test your callback URL and HTTP/HTTPS connection on Google Checkout module configuration page click the Additional information >>> link. Click Test callback URL button. If everything is set up correctly, "Trying to access the callback URL ... SUCCESS" line will be displayed.

Configuring the Module

After you have successfully installed the LiteCommerce Google Checkout add-on module, click on the Google Checkout module name in the list of installed modules to enter the module configuration page.

The following configuration settings are available:

Account options

Merchant ID: this is a unique, numeric code assigned to your business by Google. To find your Merchant ID, sign in to Google Checkout and click the 'Settings' tab. Your Merchant ID will appear under 'Primary contact information.'

Merchant key: this is a unique, alphanumeric code that helps secure your communications with Google. Both you and Google will use this key to authenticate and verify the integrity of any messages you exchange.

To find your Merchant Key, sign in to Google Checkout and click the 'Settings' tab, then click 'Integration'. Your Merchant Key will appear under 'Account information.'

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.

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

Use non-secure HTTP protocol: select this checkbox to use HTTP instead of HTTPS for communication between LiteCommerce and Google.

Seller account currency: only USD or GBP are available at present.

Order specific options

The following group of options allows you to specify which order statuses you wish to assign to your Google Checkout orders.

Order prefix: add a prefix to all your orders if you want them to be easily distinguished. For example, if you have multiple stores and use one Google Checkout account. Corresponding order prefixes will help to distinguished between the orders coming from different stores.

When you receive orders, Google authorizes the buyer's credit card for the amount of the purchase. During this authorization period, you won't be able to charge the buyer for the order. (The authorization typically takes only a few minutes, but may take up to 24 hours in certain rare cases.) After the authorization is completed, the order acquires a 'CHARGEABLE' order status, which means you can now charge this order manually.

If you have LiteCommerce AOM add-on module, it is possible to create order statuses which directly correspond with Google Checkout order statuses. For example to be able to distinguish orders that use Google Checkout as a payment method, you can create 'Google_chargeable', 'Google_charged' and 'Google_failed' statuses.

'CHARGEABLE' order status: select an existing LiteCommerce order status from the corresponding drop-down box.

'CHARGED' order status: select an existing LiteCommerce order status that will be assigned to the order which has been charged.

Declined/Canceled/Failed order status: select an existing LiteCommerce order status that will be assigned to the order which has been declined, canceled or failed.

Conditions on which orders will 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.

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.

• Send order notification emails from: Specify whether you wish order placement notifications from LC-store to be sent to customers placing orders through Google Checkout.

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, LiteCommerce 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 to notify your customers that some of the products they have added to cart are not available through Google Checkout.
• Remove discounts and gift certificates from order: select this check box to remove all discounts, gift certificates and bonus points from the final order in Google Checkout.

All of the above are added to the order as products with negative prices. That is why you might want to remove them first to exclude the possibility of a negative subtotal. The customers will have to enter the codes for discount coupons and/or gift certificates once again on the Google Checkout page. (Bonus points cannot be used to pay for orders on the Google Checkout side, only if entered directly in LiteCommerce). If you leave the check box empty, negative subtotal can be calculated.

After you complete all the required fields click 'Update' to save the information.

Disabling Google Checkout for some products

Google Checkout cannot be used for certain types of products (see Google Checkout: Content policies 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. At the bottom of the page select 'Yes' in the 'Disable Google Checkout for this product' drop-down box.

3. Click the 'Update' button.

Processing Google Checkout Orders

Reviewing the order

The merchant is 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 sales department email address by LiteCommerce (The latter is sent only if the respective notification is enabled in the 'General settings->Email' options). The merchant can then access the order through the store's admin menu, review the order details and process it.

The details pertaining to Google Checkout are displayed at the bottom of the order details page like so:

The full details of communication of the LiteCommerce-based store and Google can be recorded to the log file created by LiteCommerce. To enable logging, edit the 'Logging details' section of the etc/config.php file: delete the semicolon before "type = file" and add a semicolon before "type = "null". By default the log file is named xlite.log and created in the var/log directory.

Processing of Google Checkout orders is performed using the 'Google Checkout' tab of the 'Order details' page. 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 select the 'Google Checkout' tab. The section 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.

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

Financial commands

Charge order command

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.

Once the charge is completed, the financial order state will become CHARGED. The status of the order in LiteCommerce will be updated to Processed.

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 LiteCommerce will become Failed.

Cancel order command

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.

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 command

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. 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 LiteCommerce, the order financial state will be updated to REFUNDED. The refund amount will be displayed in red in the 'Google Checkout order details' section.

The 'Refund order' command will not affect the LiteCommerce 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 the AOM (Advanced Order Management) add-on module.

Fulfillment commands

Process order command

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 'Google Checkout' subsection. The order's fulfillment state will be updated to PROCESSING.

The 'Process order' command does not affect the order's LiteCommerce status.

Add tracking data command

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.

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 command

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 e-mail 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 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 e-mail 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 at the top of the page.

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 e-mail to the customer' check box before clicking the 'Send message' button.

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.

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 an Information box.

Customer zone

When Google Checkout module is enabled and configured, customers shop at the store as usual adding items to the shopping cart. When they view the contents of the cart, two checkout options are available: regular LiteCommerce checkout or Google Checkout.

After the customer clicks the 'Google Checkout' button the customer is redirected to Google Checkout where 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.

The coupons created directly in Google Checkout cannot be applied to the orders placed to a LiteCommerce-based store. Such coupon codes are not in the store database and will be ignored.

After the customer selects a shipping address or enters a gift certificate or coupon code 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.

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 LiteCommerce with the status Queued.

If the 'Remove discounts and gift certificates from order' option is enabled, all the discount coupons and gift certificates the customer used to pay for the order will be removed from the order to eliminate the possibility of a negative subtotal. A corresponding note is displayed to the customers, asking them to provide the codes for discount coupons and gift certificates once again on the Google Checkout side.

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.