WindowsDevCenter.com
oreilly.comSafari Books Online.Conferences.

advertisement


AddThis Social Bookmark Button

Build a .NET App for Google Checkout
Pages: 1, 2, 3, 4

Sample Code Overview

The code is open source and available with Subversion from https://google-checkout-dotnet-sample-code.googlecode.com/svn.



The heart of the code, but also the file you are the least likely to edit, is apiv2.cs. That file contains the autogenerated classes that compose and parse XML. The file was created from Google's Checkout XSD file using the tool xsd.exe, which is part of the .NET SDK.

As a quick recap, XSD stands for XML Schema Definition. XSD files describe the structure of XML documents. For example, Google's Checkout XSD file describes an element named <item> that is used for describing an individual order line in an order, among others. The XSD file tells us that the <item> element must contain subelements named <item-name> and <item-description>, and that these subelements are strings.

Most modern programming environments have tools that generate code based on XSD files. The generated code can compose and parse XML, so the developer only has to work with objects, not actual XML strings. For example, the generated code contains a class called Item with the string properties ItemName and ItemDescription.

The sample code project contains three folders, one for posting carts, one for the order processing API, and one for the merchant-calculation Callback API. The Notification API does not have its own folder because it turns out no extra classes are needed beyond the generated ones. We will see how this works later in this article.

Examples of How To Use the .NET Sample Code

After a lot of talk, it's finally time to try out the .NET sample code for Checkout. If you want to follow along at home, you need to first take these two steps:

  1. Download the sample code. You can either download the full source code using SVN from https://google-checkout-dotnet-sample-code.googlecode.com/svn, or you can get the compiled DLL file from http://code.google.com/apis/checkout/samplecode.html.
  2. Create a Sandbox merchant account. Sandbox is Google Checkout's test environment. It works like the Production environment, except that credit cards are not charged. The Sandbox registration process starts here: https://sandbox.google.com/sell.
Posting A Cart

First, the .NET code needs to know whether to hit Sandbox or Production, as well as which merchant account to add the order to. Add these keys to your web.config file:

<add key="GoogleEnvironment" value="Sandbox" />
<add key="GoogleMerchantID"  value="X" />
<add key="GoogleMerchantKey" value="Y" />

To find X and Y, log in to your Sandbox merchant account, click the Settings tab, and then click the Integration link; see Figure 5.

Figure 5
Figure 5: Finding the X and Y values

If you already have a web-based storefront, your shopping cart page is a good place to add a Google Checkout button. Drop the GCheckout.dll file into your web application's bin directory and add these page directives at the top of the cart ASPX page:

<%@ Import Namespace="GCheckout.Checkout" %>
<%@ Import Namespace="GCheckout.Util" %>
<%@ Register TagPrefix="cc1" Namespace="GCheckout.Checkout" Assembly="GCheckout" %>

Then you are ready to add the Checkout button itself:

<cc1:GCheckoutButton id="GCheckoutButton1" onclick="PostCartToGoogle" runat="server"/>

If you don't have a <form> tag on the page already, make sure you put one in around the CheckoutButton tag. Then you need to implement the method that will be called when the user clicks the Checkout button. This is the value of the GCheckoutButton tag's onclick attribute--PostCartToGoogle in the example above.

private void PostCartToGoogle(object sender, System.Web.UI.ImageClickEventArgs e) {
  CheckoutShoppingCartRequest Req = GCheckoutButton1.CreateRequest();
  Req.AddItem("Mars bar", "Packed with peanuts", 0.75m, 2);
  Req.AddFlatRateShippingMethod("SuperSaver", 2.50m);
  Req.AddFlatRateShippingMethod("Standard Ground", 5.00m);
  Req.AddStateTaxRule("CA", 0.0875, true);
  GCheckoutResponse Resp = Req.Send();
  Response.Redirect(Resp.RedirectUrl, true);
}

This code creates a CheckoutShoppingCartRequest object and adds a single order line (two Mars bars at 75 cents each) to it. Then two shipping options are added (SuperSaver for $2.50 and Standard Ground for $5.00) and a tax rule saying that California residents will be charged 8.75 percent sales tax. Finally the CheckoutShoppingCartRequest is sent to Google. Google logs the order and returns the URL to which the user should be redirected.

If you point your browser to your local cart page and click the Checkout button, you will see a page from Google's Sandbox environment (Figure 6.)

Figure 6
Figure 6: A page from the Google Sandbox environment

If you log in or create a new account, Google will show you the shipping options and add sales tax if your currently selected shipping address is in California (Figure 7). You will also see the Place Order button. Feel free to click it. This is the Sandbox environment, so your credit card won't be charged.

Figure 7
Figure 7: Shipping options and sales tax being added

This is the bare minimum Checkout integration. All you have to do to start selling is to create a Production merchant account (by going to http://checkout.google.com/sell), put that account's ID and key in web.config, and set GoogleEnvironment to Production in web.config. You can now accept real orders! If you want more of an industrial-strength integration, read on.

Notification API

Merchants integrate with this API to automatically transfer Google Checkout orders and order statuses into their existing order database. To do this in .NET, create an ASPX page that will accept the notifications from Google. Then tell Google the URL of that page by logging in to your merchant account and entering the URL into the API callback URL text field. Make sure the callback method is set to XML (Figure 8).

Figure 8
Figure 8: Making sure the callback method is set to XML

Now let's write the page that will receive the notifications from Google. Here is a good start:

<%@ Import Namespace="System.IO" %>
<%@ Import Namespace="GCheckout" %>
<%@ Import Namespace="GCheckout.AutoGen" %>
<%@ Import Namespace="GCheckout.Util" %>
<script runat="server" language="c#">

  void Page_Load(Object sender, EventArgs e) {
    // Extract the XML from the request.
    Stream RequestStream = Request.InputStream;
    StreamReader RequestStreamReader = new StreamReader(RequestStream);
    string RequestXml = RequestStreamReader.ReadToEnd();
    RequestStream.Close();
    // Act on the XML.
    switch (EncodeHelper.GetTopElement(RequestXml)) {
      case "new-order-notification":
        NewOrderNotification N1 = (NewOrderNotification) EncodeHelper.Deserialize(RequestXml, typeof(NewOrderNotification));
        string OrderNumber1 = N1.googleordernumber;
        string ShipToName = N1.buyershippingaddress.contactname;
        string ShipToAddress1 = N1.buyershippingaddress.address1;
        string ShipToAddress2 = N1.buyershippingaddress.address2;
        string ShipToCity = N1.buyershippingaddress.city;
        string ShipToState = N1.buyershippingaddress.region;
        string ShipToZip = N1.buyershippingaddress.postalcode;
        foreach (Item ThisItem in N1.shoppingcart.items) {
          string Name = ThisItem.itemname;
          int Quantity = ThisItem.quantity;
          decimal Price = ThisItem.unitprice.Value;
        }
        break;
      default:
        break;
    }
  }

</script>
<?xml version="1.0" encoding="UTF-8"?>
<notification-acknowledgment xmlns="http://checkout.google.com/schema/2"/>

The Page_Load() method starts by reading the XML sent from Google. Notice that Google does not use SOAP, so you can't leverage the .NET framework for converting SOAP messages to method calls. Google uses HTTP POST to send XML to merchants, with the XML in the payload of the HTTP packet. So you have to open a stream to read the XML.

Once that has been done, there is a switch statement with a case for each type of notification. So far, only the new-order-notification has been implemented. When such a notification is received, a NewOrderNotification object is created. You can read useful data from this object, like order number and shipping address of the order. You can also loop over the individual order lines. After that, you have all the data needed to create an order record in your existing order database. That's all it takes to automatically transfer newly placed orders from Checkout to your existing system.

The new-order-notification is only one of the notifications Google sends to merchants. Here are case statements for the others, suitable for putting in the switch statement in the code above.

      case "risk-information-notification":
        RiskInformationNotification N2 = (RiskInformationNotification) EncodeHelper.Deserialize(RequestXml, typeof(RiskInformationNotification));
        // This notification tells us that Google has authorized the order and it has passed the fraud check.
        // Use the data below to determine if you want to accept the order, then start processing it.
        string OrderNumber2 = N2.googleordernumber;
        string AVS = N2.riskinformation.avsresponse;
        string CVN = N2.riskinformation.cvnresponse;
        bool SellerProtection = N2.riskinformation.eligibleforprotection;
        break;
      case "order-state-change-notification":
        OrderStateChangeNotification N3 = (OrderStateChangeNotification) EncodeHelper.Deserialize(RequestXml, typeof(OrderStateChangeNotification));
        // The order has changed either financial or fulfillment state in Google's system.
        string OrderNumber3 = N3.googleordernumber;
        string NewFinanceState = N3.newfinancialorderstate.ToString();
        string NewFulfillmentState = N3.newfulfillmentorderstate.ToString();
        string PrevFinanceState = N3.previousfinancialorderstate.ToString();
        string PrevFulfillmentState = N3.previousfulfillmentorderstate.ToString();
        break;
      case "charge-amount-notification":
        ChargeAmountNotification N4 = (ChargeAmountNotification) EncodeHelper.Deserialize(RequestXml, typeof(ChargeAmountNotification));
        // Google has successfully charged the customer's credit card.
        string OrderNumber4 = N4.googleordernumber;
        decimal ChargedAmount = N4.latestchargeamount.Value;
        break;
      case "refund-amount-notification":
        RefundAmountNotification N5 = (RefundAmountNotification) EncodeHelper.Deserialize(RequestXml, typeof(RefundAmountNotification));
        // Google has successfully refunded the customer's credit card.
        string OrderNumber5 = N5.googleordernumber;
        decimal RefundedAmount = N5.latestrefundamount.Value;
        break;
      case "chargeback-amount-notification":
        ChargebackAmountNotification N6 = (ChargebackAmountNotification) EncodeHelper.Deserialize(RequestXml, typeof(ChargebackAmountNotification));
        // A customer initiated a chargeback with his credit card company to get her money back.
        string OrderNumber6 = N6.googleordernumber;
        decimal ChargebackAmount = N6.latestchargebackamount.Value;
        break;

The most important of these notifications is the risk-information-notification. The new-order-notification tells you that a new order has been placed, but you may not want to start processing it yet because the customer's credit card has not been authorized. Once it has been authorized, you will get the risk-information-notification. Given the results of the AVS and CVV/CVN checks and the order's protection status, you should make a decision if you want to accept the order. If you don't accept it, you should cancel it and let the customer know why you did so. If you accept it, you should start processing it.

If AVS and CVV/CVN are unfamiliar terms, you can find good introductions here: http://en.wikipedia.org/wiki/Address_Verification_System and http://en.wikipedia.org/wiki/Card_Security_Code. For more information about the other notifications read by the code above, see Google's Checkout Dev Guide.

Pages: 1, 2, 3, 4

Next Pagearrow