Posts from the 'eCommerce' Category

How to move from Google Checkout’s HTML API to the XML API (in PHP)

We recently moved a client’s Google Checkout solution from the HTML API to the XML API. It seemed tough when we were doing it but if we had to do it again now it would be a breeze. So the goal of this article is to save you the hassle of learning the steps of how to move from the HTML API to the XML API.

What you’ll need:

  • A Google Merchant account
  • A Google Sandbox account (can be part of the Merchant account)

Procedure:

Step 1 – Get the Google Libraries and Example carts

First stop, take a quick look the Google Developer page for Checkout users – this is your portal into Google as a Google Checkout developer.

Now take a look at the XML API page. We built our cart using PHP, so we used the PHP examples. Examples in other languages can be found here. Again, it’s worth taking a minute to familiarize yourself with this page.

And now for the good news – Google Sample Code for creating an XML API cart. We went to the PHP category and clicked on the download link to get the sample code. This little bundle contains pretty much everything you need to build a Google XML API cart quickly and easily.

Step 2 – Open the sample code and take a look inside

Inside the folder you just downloaded you’ll see a lot of stuff. There are only two folders that you need concern yourself with however.

  • Library – Our favourite because it contains all of the code you’ll need to create you XML documents and yet you will probably never have to touch a single line of the code in here. It’s all ready for you – these are libraries, code that is prepared for you, if you like.
  • Demo – Almost as good! All you have to do is look at the examples in here, tweak them so they use your own data instead and test it in your Google Sandbox.

Step 3 – Setting it up

Now you’ve got your code Libraries and Demo files, you’re ready to upload them, modify them and test them in your Sandbox. Here’s how:

  • Upload the sample code to your server. We created a folder called Google_Checkout and dropped the “demo”, “library” and “unitTest” folders in there.
  • Navigate to Demo>cartdemo.php and make a backup before we start hacking at it
  • Open cartdemo.php from on your server and scroll down to where you see this:
     // Invoke any of the provided use cases
    // UseCase1();
    // UseCase2();
    // UseCase3();
    Usecase();
    DigitalUsecase();
    CarrierCalcUsecase();

    The Google coders have thoughtfully provided you with various different types of cart to play with all in this single file. We’re only going to use one of them, so comment the code so it looks like this. You can experiment with the other options later once you’ve understood the basics.:

     // Invoke any of the provided use cases
    // UseCase1();
    // UseCase2();
    // UseCase3();
    Usecase();
    // DigitalUsecase();
    // CarrierCalcUsecase();

    Great! Step one is complete and your cart will only use one calculation method: the one called Usecase();

  • Now we need to go and get our Sandbox merchant ID and Key. Where? Login to your Google Checkout merchant’s account click on “My Account” then “Checkout Sandbox” then go to your “Settings” tab. Your Sandbox ID and Key should be on the right or under the integration link (bottom left)
  • Return to cartdemo.php and a few lines down from where we left off you’ll see:
    
          $merchant_id = "";  // Your Merchant ID
    $merchant_key = ""; // Your Merchant Key
    $server_type = "sandbox";
    $currency = "USD";

    Just fill in your sandbox info for Merchant ID and Key and we’re good to go!

  • Now we’ll check the Sandbox is working. Load the cartdemo.php page into your browser via the server (http://anExample.com/Google_Checkout/Demo/cartdemo.php

    You should see a Google Button. Click on it and you’ll be taken to the Sandbox checkout and in the background… your site created the requisite XML!!!

Step 4 – Integrate your basket

Now the Sandbox is working in XML mode all you have to do is modify the predefined cart items that Google provides with your own. Here’s how:

  • Navigate to the lines of code just a little further down in the cartdemo.php page. You should see this:
    $item_1 = new GoogleItem("item name", // Item name
    "item desc", // Item description
    $total_count, // Quantity
    10); // Unit price
    $cart->AddItem($item_1);

    And happily, from here on in it’s really simple. Just create a loop for however many different items there are in your basket and build your basket. Here’s a possible example:

    
    foreach ($_SESSION['theCart'] as $line){ //The 'theCart' session is a basket array.
    $num_items = $line['Qty']; //Basic info about each item
    $item_price = ($line['unit_price']);
    $item_name = strtoupper(($line['unit_name']));
    $item_category = ($line['unit_category']); //Something like the Google Description
    // Create cart item
    //The curly braces allow the appending of
    //a numeric suffix to a varible you are creating
    ${"item_".$x} = new GoogleItem($item_name, // Item name
    $item_category, // Item description
    //If you use Carrier Calculated shipping you must provide weight
    $the_weight = (($line['unit_weight'])/16);
    $num_items, // Quantity
    $item_price, // Unit price
    'LB',
    $the_weight //Item Weight
    );

    // Add items to the cart
    $cart->AddItem(${"item_".$x});

    $x++; //Increase count

    } //end foreach line item

    } else {

    echo "No Valid Basket - Sorry!!!!!";
    }

Step 5 – Getting ready to go live

OK, you’ve done the above but your wondering how to put all of this into your checkout page. Take a look! Just put this line of code where your existing HTML API Google Checkout button is:

<?php include '/Google_Checkout/Demo/cartdemo.php'; ?>

We’re kidding, right? Nope! You can now throw away all those input hidden statements you were using previously and put this single line. THe XML is all generated by that single include.

If you want to see the XML being created for debugging, go to the bottom of your usecase() function (not necessarily the bottom of the document) and uncomment this:

// Display XML data
// echo "<pre>";
// echo htmlentities($cart->GetXML());
// echo "</pre>";

Step 6 – Set Shipping and Tax options

One of the big advantages of using the XML API is that it allows you a lot more control over shipping and taxes. There are a multitude of possibilities here and to get the most out of them you should take a look at the Google XML API guide. There are further documents linked to that deal with Carrier Calculated shipping, Taxes, etc.

If you’re using our Usecase() example basket, you’ll see some shipping and tax options have already been set:

  // Add shipping options
  if($total_count < 3){
		 $ship_1 = new GoogleFlatRateShipping("USPS Priority Mail", 4.55);
  }else{
		 $ship_1 = new GoogleFlatRateShipping("USPS Priority Mail", 6.2);
  }
  $Gfilter = new GoogleShippingFilters();
  $Gfilter->SetAllowedCountryArea('CONTINENTAL_48');
  
  $ship_1->AddShippingRestrictions($Gfilter);
  
  $cart->AddShipping($ship_1);
  
  // Add tax rules
  $tax_rule = new GoogleDefaultTaxRule(0.05);
  $tax_rule->SetStateAreas(array("MA"));
  $cart->AddDefaultTaxRules($tax_rule);
  
  // Specify 
  $cart->SetEditCartUrl("https://www.example.com/cart/");
  
  // Specify "Return to xyz" link
  $cart->SetContinueShoppingUrl("https://www.example.com/goods/");
  
  // Request buyer's phone number
  $cart->SetRequestBuyerPhone(true);
  
  // Display Google Checkout button
  echo $cart->CheckoutButtonCode("SMALL");

This should all be fairly self explanatory. There are loads more examples throughout the demo file so scroll on down and take a look.

Step 7 – Put it live

If everything is happening as expected you can then put your basket live.

  • Return to your Google Merchant’s Account, leave the Sandbox area and go to your actual account information. Get your ID and Key and use them instead of the Sandbox values (see step 3 point 5 above). You’ll also need to change the line $server_type = “sandbox”; to $server_type = “checkout”;
  • That’s it – you’re live!

Disclaimer

Metaclarity does everything it can to ensure the information we post is accurate. However, Metaclarity can accept no responsibilty for any damage or loss of data use of the above information might cause.