My favorites | English | Sign in

Google Checkout

Custom Order Processing: HTML API

Contents
Step 1. Set up server to receive notifications
Step 2. Handle order notification messages
Step 3. Charge, ship and archive the order
Step 4. Handle refund/return or chargeback
Step 5. Test your Checkout implementation
Step 6. Push Checkout live
Getting paid
Integrating Google Checkout with your Custom Order Processing System

This document is a step-by-step procedure instructing you on how to integrate Google Checkout with your custom order processing system. It assumes that you have an existing order processing system and want to integrate Google Checkout using the HTML API. As explained below, integrating requires programming skills to modify your server code.

Objective: When you're done, you'll be able to receive and handle Google Checkout orders in an automated manner.

This procedure uses the HTML API. If you're unsure whether you should be using the HTML or XML API, see Choosing Between HTML and XML API (http://code.google.com/apis/checkout/developer/Google_Checkout_HTMLorXML_Processing.html).

Will this procedure work for my site?

  • This procedure will work for you if you have your own internal order processing system that you'd like to have handle Google Checkout orders. You will need a server capable of receiving notifications, and a programmer capable of writing custom code to integrate your system.

Procedure Summary:

  • You configure your server and SSL certificate to communicate with the Google Checkout server.
  • You modify your server code to parse any received notifications, then programmatically generate responses.

Assumptions:

  • You have already implemented a method for accepting Google Checkout orders (http://code.google.com/apis/checkout/developer/Google_Checkout_Comparison_Part_I.html).
  • You have an SSL certificate with an accepted root certificate (http://checkout.google.com/support/sell/bin/answer.py?hl=en&answer=57856)(Required for Notification API)
  • You can configure the basic authentication on your server (http://code.google.com/apis/checkout/developer/Google_Checkout_Glossary.html#http_basic_authentication)(Required for Notification API)

Technical Skills Required:

    The programmer responsible for implementing order processing with Google Checkout via the API should have a strong working knowledge of:
  • Server-side code that can parse and write out HTML requests. The programming language is dictated by what the rest of your website is written in, such as PHP, Perl, Python, ASP, ASP.NET, Java or equivalent.

This symbol means the link opens up the page in a new window or tab so when you're done with that step, you can close the window or tab and return to the next step.

Step 1. Set up server to receive notifications

  1. Configure your server's basic authentication.

    You'll need to configure basic authentication on this server to accept your Merchant ID and Merchant Key as a login and password. You may wish to ask your hosting provider or review your server instructions for configuration details, as they will differ for each server software.

  2. Install a Google Checkout-accepted SSL certificate.

    The currently accepted root certificates can be found in the following list: Accepted SSL Certificates (http://checkout.google.com/support/sell/bin/answer.py?hl=en&answer=57856). As certificate names don't always indicate their root certificate, you may need to check with the certificate provider.

    Once your certificate is installed, you can check whether you return the entire certificate chain correctly by running the following command (with your actual website domain) in Unix, or after downloading OpenSSL for Windows:

    openssl s_client -connect {website domain}:443 -showcerts < /dev/null

    If your certificate hierarchy isn't correct, you won't be able to accept notifications from Google Checkout.

Step 2. Handle order notification messages (Notification API)

Note: This step can be performed by using the Notification API (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Notification_API.html), the Notification History API, or the Polling API. This document will cover the most common method, the Notification API, which provides real-time notifications of new orders and order state changes.

Here are the typical messages associated with an order:

  • New Order Notifications (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Notification_API.html#new_order_notifications) informs you of new orders that have been submitted through Google Checkout.
  • Risk Information Notifications (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Notification_API.html#risk_information_notification) provides financial information about a transaction to help you ensure that an order is not fraudulent.
  • Order State Change Notifications (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Notification_API.html#order_state_change_notification) signals an update to an order's financial status or its fulfillment status.
  • Amount Notifications (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Notification_API.html#amount_notifications) informs you that a charge, refund, chargeback or credit card authorization has been processed for an order. These notifications also identify the amount of the transaction.

The New Order Notification comes first; other notifications can be in any order.

The steps you will need to do are:

  1. Receive and parse notifications

    You first need to handle the New Order, Risk, and Order State Change notifications. These notifications will provide information about the order state, order contents, and buyer.

    Your server will need to receive and parse these notifications for the information that's pertinent to your order processing system. You can leverage our client libraries (http://code.google.com/apis/checkout/samplecode.html) to help handle these notifications.

    The possible order state changes are defined by financial-order-state (http://code.google.com/apis/checkout/Google_Checkout_HTML_API_Parameter_Reference.html#tag_financial-order_state) and fulfillment-order-state (http://code.google.com/apis/checkout/Google_Checkout_HTML_API_Parameter_Reference.html#tag_fulfullment-order-state).

    Values for financial-order-state include:

    • REVIEWING - Google Checkout is reviewing the order.
    • CHARGEABLE - The order is ready to be charged.
    • CHARGING - The order is being charged; you may not refund or cancel an order until is the charge is completed.
    • CHARGED - The order has been successfully charged.
    • PAYMENT_DECLINED - The charge attempt failed.
    • CANCELLED - Either the buyer or 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.

    Values for fulfillment-order-state include:

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

    You can use this financial-order-state and fullment-order-state to determine how and when to process an order. For example, when the financial-order-state becomes chargeable, you can send the charge-order (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Financial_Commands.html#Charge_Order) request to capture payment.

  2. Store information from the notification and determine the appropriate response

    Once the notification has been parsed, you need to create custom logic to store the necessary information and process the order accordingly. For example, a New Order Notification should cause the creation of that order in your database.

    The typical notification flow for an order is shown in the following diagram. To read details about the steps in this diagram, see Typical order flow (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Processing.html#typical_order_flow).

Take a look at the Notification API (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Notification_API.html) for more details on what parameters the notifications might include.

Step 3. Charge, ship and archive the order (Order Processing API)

  1. Once an order becomes chargeable, and the order is ready to ship, send the charge-order (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Financial_Commands.html#Charge_Order) request to the appropriate order processing URL, with the string MERCHANT_ID replaced with your actual numeric Merchant ID:

    • Sandbox:

      https://sandbox.google.com/checkout/api/checkout/v2/requestForm/Merchant/MERCHANT_ID

    • Production:

      https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID

    NOTE: You should do all your testing in a sandbox environment. Remember that you will have different Merchant IDs for your production and sandbox accounts.

    Charging the order prompts Google Checkout to actually collect funds from the buyer, and will schedule a payout to you if the charge is successful.

    You can view sample code (http://code.google.com/apis/checkout/samplecode.html) for examples on issuing charge-order requests.

  2. Receive an order-state-change-notification (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Notification_API.html#order_state_change_notification) with a new-financial-order-state (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Parameter_Reference.html#tag_new-financial-order-state) of CHARGED (which confirms the charge was completed successfully) and a charge-amount-notification (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Notification_API.html#charge_amount_notification) (which specifies how much money was charged) for the charged amount.

  3. Ship the order within 24 hours and send a deliver-order (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Order_Level_Shipping.html#Deliver_Order) command to update the fulfillment status with Google Checkout. By default, this command will provide an email update to the buyer.

  4. Receive an order-state-change-notification with a new-fulfillment-order-state (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Parameter_Reference.html#tag_new-fulfillment-order-state) of DELIVERED to confirm that Google Checkout successfully received the deliver-order request.

  5. Once the order is completely fulfilled, send the archive-order (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Archiving_Commands.html#Archive_Order) request.

For more details on specific commands, see:

  • Financial commands (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Financial_Commands.html)
  • Line-item shipping (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Line_Item_Shipping.html)
  • Order-level shipping (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Order_Level_Shipping.html)
  • Archiving commands (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Archiving_Commands.html)

Step 4. Handle refund/return or chargeback

While most orders are complete by this stage, some may be returned, need to be refunded, or become charged back.

Refunds and returns

To handle a refund, you'll need to:

  1. Issue a refund-order (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Financial_Commands.html#Refund_Order) request. You can refund all or part of an order.
  2. If part or all of the order was returned, send a return-items (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Line_Item_Shipping.html#Return_Items) command.
  3. Handle the refund-amount-notification (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Notification_API.html#refund_amount_notification).

If the refund is for the complete order, you can issue a cancel-order (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Financial_Commands.html#Cancel_Order) request to the same effect.

Chargebacks

If an order becomes charged back, you'll receive a chargeback-amount-notification (http://code.google.com/apis/checkout/developer/Google_Checkout_HTML_API_Notification_API.html#chargeback_amount_notification).

Step 5. Test your Checkout implementation

To test your Google Checkout implementation, be sure to use the sandbox server URL with your sandbox Merchant ID when sending commands, then try some end-to-end orders and check the following is true:

  • Your server is set up correctly and you can receive notifications.
  • You can pull out necessary attributes from notifications.
  • You can send order processing commands to the Google Checkout server.
  • There are no notification reception / order processing infinite loops.
  • Orders are being stored on your system.

If you experience any problems, you can check the Integration Console (https://sandbox.google.com/checkout/sell/settings?section=IntegrationConsole) in your sandbox Merchant Center to view a log of any API error and warning messages.

Step 6. Push Checkout live

If you've been using the sandbox, you need to make the following changes:

  • Change the sandbox URL to the production URL for all order processing requests: 
    https://checkout.google.com/api/checkout/v2/requestForm/Merchant/MERCHANT_ID
  • Replace your sandbox Merchant ID and Merchant Key with your production Merchant ID and Merchant Key.

Once you're sure you can fulfill orders, go ahead and push your site live.

You're done integrating Google Checkout order processing!

Congratulations!

Getting paid

After a buyer has placed an order, you have shipped it to them and charged their card, Google then pays you that amount minus a transaction fee. To find out about payment prerequisites and schedules, see: