Sitecore E-Commerce Services Part 4 - Checkout

Thursday, January 02, 2014 @ 02:26
Sitecore E-Commerce Services Part 4 – Checkout

By: Dusty Eves, Senior Developer 

Checkout Defined

So now that users can add items to their cart we need to give customers the ability to turn their carts into an order via checkout.  Depending on the nature of what you’re selling, checkout processes very from site to site.  Most checkout process will include some variation of the following:

  • Cart Review
  • Shipping Method
  • Shipping and Billing Address
  • Payment
  • Order Confirmation

Cart Review

The shopping cart page we've setup in the previous tutorial will serve as a starting point for our shopping cart review page.  We just need to extend it to include price totals and a button to get us to the next checkout step.

The Totals property of your active shopping cart are straight-forward to retrieve, but there's a great deal more to it than one might guess at first glance. What price lines you display will vary depending on your site, for now we'll just grab the TotalPriceIncVat and display in the format of the site Currency display setting.  If you've not yet set said property in can be found under Webshop Site Settings/General “Price Format String”.

Once we're showing price all we need is a next button to move to the next checkout step.



Our next step our shipping page.  Before we dig into the meat of the page we have some scaffolding to do.  First step is to setup a handful of shipping methods under /MySite/BusinessCatalog/Shipping Options.  The Shipping Provider template gives us the most simple use case for shipping providing fields for a designation, description, icon, price, and deliver time frame.  This can be extended to for more complex use case but we'll go with simple case for the moment.  Once you've an option or two setup you need to set this as your site's shipping provider.  Under Webshop Site Settings/Business Catalog set the Shipping Providers Link field to point to the Shipping Options node we just populated.

Now we can stand up our shipping page.  As for all our checkout pages, create a simple page and a corresponding sublayout for our functionality.  To retrieve the shipping methods the domain model as always provides us with a ShippingProvider.  Binding the methods to a list or repeater is quite straight-forward, and beyond that we need only a button to navigate to the next checkout step.

In navigating to the next checkout step though we need to record the shipping method selection.  We record this selection by assigning it to the active cart's shipping provider.  In addition, also assign the shipping price to the cart, as it doesn't carry intrinsically with the provider.


Billing and Shipping Address

The billing and shipping address of an order are innately tied to the customer account of that order.  While SES supports anonymous checkout for our example we'll assume the user is logged in. 

First order of business for our address screen is to populate the existing customer address data.  Both shipping and billing addresses are available via the CurrentUser.ShippingAddress and CurrentUser.Billing address.  Once pulled we just bind it directly to our form.

Getting the data is pretty straight-forward but what we do with it on clicking next is a little more nuanced.  Our first step here is to assign the CurrentUser to the CustomerInfo property of the active cart.  While the details the active cart's CustomerInfo may change this will establish our baseline.  The simplest use case is the addresses for the order match what the customer currently has in his profile.  If this is the case once we have assign the active cart's CustomerInfo property we can proceed to the next step.  The other use case we need to cover is departing from what's in the profile.  A checkbox allowing the user to explicate an alternate address will lay the scaffolding for this use case.  If this is check, we then go through the detail properties of CustomerInfo on the active cart and assign the new address properties there.

While not strictly required for the checkout process, an additional checkbox to provide a mechanism for the user to update their profile with the new address info can be valuable here.  If checked, simply call the UpdateCustomerProfile method from the customer manager and pass in the CustomerInfo from the active cart.



The payment mechanism for SES hosted payment providers, such as PayPal or Google Checkout.  If you want your customers to be able to complete checkout without leaving your site it is possible to self-host your payment form but for now we'll use an offline payment provider (Keep watching here for how-to's on hosted and self-hosted payment forms will be coming). 

The first bit of scaffolding we need for payment processing is to setup our payment options and and point our Webshop Site Settings to said payment options.  First add a few payment options to MySite/Webshop Business Settings/Payment Options/.  Next in MySite/Webshop Site Settings/Business Catalog point the Payment Systems Link field to the aforementioned Payment Options item.

Once your payment methods are setup in Sitecore we need to tie them to a payment provider in our configuration.  In your Unity.Config file, find the payment providers section.  Create an entry for each of your created payment methods and map it to OfflinePaymentProvider matching the name fields between Sitecore and your config file.


Payment Process Routing

As said previously SES payment providers are based around hosted payment forms.  If you're unfamiliar with hosted payment processing the workflow typically breaks down as follows:

  • On payment initiation perform an http POST to the payment providers site with:

◦         Your vendor identification data

◦         Sufficient information about the order to process the charge

◦         Return URLs to your site on payment completion

  • On payment completion, http POST back to your site with:

◦         Transaction information



For our example we've setup offline payment methods but as an exercise let us still setup the artifacts to support hosted payment providers.  We'll need to setup pages and sublayouts for payment success, failure, and cancellation.  Once created, under the Payment Options item we point the return URLs to the aforementioned items.

Payment Page

So now we have most of the moving pieces in place to take the order through to completion.  As previously stated, the way we consume a hosted payment provider is to generate a post to the hosted payment page.  SES takes care of that for us with the PaymentPipeline.  But we need to provide the payment provider with an order number.  Prior to invoking the pipeline we need to assign an order number to the active cart by calling the GenerateOrderNumber method of the order manager.  Note though, before you can call the method, you need to provide a starting place.  Under /MySite/WebShop Business Settings/Orders in the content tab you'll find a Latest Order Number field, with a vociferous warning that it is not to be changed.  Such is generally sound advice as this particular piece of content is incremented as orders are created.  However, if blank the GenerateOrderNumber method will throw an exception, so make sure to provide it a starting place.


Once you've an order number just assign the order number to the active cart and invoke the payment pipeline.


Complete and Generate Order

The payment providers we've setup thus far are OfflinePaymentProviders.  As such they process the pipeline and redirects the user to the Payment Return Url configured in the Payment Options item.  As such, on our payment return/success page is where we finalize the order.  The code to create the order is quite straight-forward, all we need to do is to invoke OrderManager.CreateOrder method and pass in the active shopping cart and invoke the orderCreated pipeline and pass in the order number.  However, there are a number of prerequisites that we need to satisfy for the orderCreated pipeline to invoke successfully. 



The first item we need to satisfy is the necessary states for order creation is the necessary order states.  Order states are implemented as a series of interlink descriptors.  For our example we'll just implement our simplest case scenario.  Create a folder under Webshop Business Settings called states.  Set the insert options to /Templates/Branches/E-Commerce/State.  This creates the structure that we need.  Under the aforementioned folder create 4 states, New, Open, In Process and Closed.  You'll note underneath each state is a FollowingStates, SubStates, and SubstateCombinations folder.  Link the states in the order they were created by adding the apropriate FollowingStates to each item as below:



The next prerequisite we have to satisfy is order notification.  The de facto notification method for just about any ecommerce site is email.  The SES mail notification naturally uses Sitecore's MailServer settings.  If you've an SMTP Server easily available this is a simple matter to setup.  If not you can setup a test Gmail account for this exercise.  Setting up Sitecore to use Gmail for SMTP is a little tricky, but Mark Cassidy has a great how-to here:

Once we have our mail settings in place we need to setup the notifications.  Under Webshop Business Settings/Notification Options add a Notification Option instance called Email and set the Notification Options Link on Business Catalog to the aforementioned Notification Options folder.  Under Webshop Site Settings add a folder called MailTemplates and point your Mail Templates Link field from your General settings item to it.  Underneath it insert an instances of templates/ECommerice/Settings/Mail Template.  The one field on this item that's critical is the ‘To’ field, the rest is just content to fill in to fit your needs.  The ‘To’ field however needs to be: {BuyerCustomerParty.Party.Contact.ElectronicMail}.


And that's order creation in a nutshell.  Your exact implementation will vary greatly depending on your site and SES leaves us no shortage of place to customize the process.






More about Paragon: We're is a leading Certified Sitecore Partner in Cleveland that specializes in custom software development, Sitecore DMS, training, CMS & mobile platforms. We have some of the most experienced Sitecore developers in the nation, with over 27 Sitecore certified developers on staff and 2 Sitecore MVPs.  Paragon has a Sitecore Specialization in E-Commerce, and has vast experience building Multi-National, Multi-Branded eCommerce Sites.  Some of our clients include: The Cleveland Clinic, Forest City Enterprises, Vitamix, Charles Schwab, Ernst & Young, Major League Baseball, and Materion. Our firm offers numerous Sitecore services including development, audits, custom training, and site support and maintenance.  Our custom training offer is designed for content authors, developers, and site administrators.