# Monday, 29 November 2010

uCommerce comes with built-in support for PayEx payments. This guide will walk you through getting uCommerce to work with PayEx for payment processing.

Authorization, acquire (capture), refund, or cancel (void) are available for all plans with PayEx.

Settings in uCommerce

Add a new payment method, under “uCommerce –> Settings –> Orders –> Payment Methods”. You can call it whatever you like, here I have used “PayEx”.


Click the newly created node and select “PayEx” in the Service drop down list. Fill out the rest of the required information, like where it’s available from under the “Access” tab, pricing and the language tabs. When you are done click “Save”.


That’s everything in the uCommerce interface.

Settings in PayEx Merchant Admin Panel

Changes needed in the PayEx Merchant Admin, so it will work with uCommerce.

Ip filter

1. Click ”Merchant profile”.

2. Type in the external ip address of the webserver running the shop.

3. Click “Save”.


Merchant access list

1. Click “Merchant access list” in the menu to the left.

2. Click the “PxOrder.PxOrder” link, so it will be expanded and make sure the following is checked. If they aren’t checked, please contact PayEx support and get them to do it.

· Cancel2

· Complete

· Capture3

· Credit3


Editing the PayEx.config File

Now we need to edit the PayEx.config file.

You will find the PayEx.config file in the following location, where “rootdir” is the directory on the computer where you installed Umbraco: “rootdir\umbraco\UCommerce\Configuration\PayEx.config”. Usually “rootdir” is c:\inetpub.


Some of the below information are found in the PayEx Merchant Admin, so start by logging in you aren’t already.

Finding debug

If set to “True” you will be prompted to click a button before posting the information to “PayEx” otherwise it will do an autosubmit using Javascript. When running in production, you will want this set to “False”.

Finding testMode

This will most likely be a “False” unless you are using a test account.

Finding callbackUrl

Leave this at “(auto)” if in doubt.

Finding acceptUrl

Url the user is returned to after successfully authorizing her credit card.

Finding cancelUrl

Url the user is returned to if she cancels a purchase.

Finding accountNumber

1. Click “Merchant profile”.

2. Copy the “Merchant account” number.


Finding key

The Md5 key is created in the administration panel.

1. Click “Merchant profile” in the menu to the left.

2. Click “New encryption key”.


1. Copy the encryption key.

2. If you click “Save encryption key”, please note that it will overwrite the old one. It’s not possible to get the old key from the admin interface, so keep it in a safe place.


Executing a Pipeline on Callback

Running a pipeline once payment is authorized can be helpful if you need to complete the order once the customer returns to your site.

To run a “pipeline” once the callback if received and processed, you need to modify the database. If you used the name “PayEx” for the payment method name, you can run this SQL query in the SQL Server Management Studio.

UPDATE uCommerce_PaymentMethod SET Pipeline = 'Checkout' WHERE Name = 'PayEx'

or just edit it manually in SQL Server Management Studio.


Now the default piplline that comes with uCommerce will be run after each successful callback. This sets the Basket to an Order, gives it an OrderNumber, and other things.

Optional: Enable Acquire, Cancel, and Refund in uCommerce Back Office

To be able to acquire, cancel, and refund payments you need to enable two pipeline tasks in the ToCompletedOrder pipeline and ToCancelled pipeline.

The pipeline configuration is found in /umbraco/ucommerce/pipelines.






· Test mode – Make sure test mode if turned off when going live.

posted on Monday, 29 November 2010 13:59:52 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback

uCommerce comes with built-in support for Payer payments. This guide will walk you through getting uCommerce to work with Payer for payment processing.

Authorization is available for all plans with Payer. Payer don’t support remote acquire (capture), refund, or cancel of payments. When an authorization is made the payment is automatically captured and cannot be overridden using configuration. To refund a payment, you must use the Adminwebb.

Settings in uCommerce

Add a new payment method, under “uCommerce –> Settings –> Orders –> Payment Methods”. You can call it whatever you like, here I have used “Payer”.


Click the newly created node and select “Payer” in the Service drop down list. Fill out the rest of the required information, like where it’s available from under the “Access” tab, pricing and the language tabs. When you are done click “Save”.


That’s everything in the uCommerce interface.

Settings in Payer Administration Panel

Changes needed in the Adminwebb, so it will work with uCommerce.

Payment Methods

1. Click “Inställningar”.

2. Click ”Betalsätt”.

3. Make sure the top radio button is selected. If it’s not, select it.

4. Click the “Spare” button.


Debug options

1. Click “Inställningar”.

2. Click ”Allmänt”.

3. Make sure all three checkbox’s are unchecked, if not do it.

4. Click “Spara”.


Editing the Payer.config File

Now we need to edit the Payer.config file.

You will find the Payer.config file in the following location, where “rootdir” is the directory on the computer where you installed Umbraco: “rootdir\umbraco\UCommerce\Configuration\Payer.config”. Usually “rootdir” is c:\inetpub.


Some of the below information are found in the Adminwebb, so start by logging in you aren’t already.

Finding agentId, key1 and key2

In the compressed starting package, "Startpaket", you can find the Agent ID and the keys beneath the catalog "Resources", in the files called "PayReadConf.*".

Finding debug

If set to “True” you will be prompted to click a button before posting the information to “ePay” otherwise it will do an autosubmit using Javascript. When running in production, you will want this set to “False”.

Finding testMode

This setting must match the configuration in the Adminwebb. If you followed the steps in “Debug options” above, you should set this to “False”, indicating that we are running in production.

Finding callback

Leave this at “(auto)” if in doubt.

Finding acceptUrl

Url the user is returned to after successfully authorizing her credit card.

Finding cancelUrl

Url the user is returned to if she cancels a purchase.

Executing a Pipeline on Callback

Running a pipeline once payment is authorized can be helpful if you need to complete the order once the customer returns to your site.

To run a “pipeline” once the callback if received and processed, you need to modify the database. If you used the name “Payer” for the payment method name, you can run this SQL query in the SQL Server Management Studio.

UPDATE uCommerce_PaymentMethod SET Pipeline = 'Checkout' WHERE Name = 'Payer'

or just edit it manually in SQL Server Management Studio.


Now the default piplline that comes with uCommerce will be run after each successful callback. This sets the Basket to an Order, gives it an OrderNumber, and other things.

posted on Monday, 29 November 2010 13:57:02 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Monday, 22 November 2010

Once in a while a question turns up in the uCommerce support forum which has me stumped for while. As usual with LINQ once the solution presents itself it turns out to be quite simple, dare I say elegant?

So what was the question again? We need a way to find all products present in number of categories as specified by a customer, think search. So we only want products present in both categories A and B, but not products only present in only one or the other.

Here’s how you’d do that:

// These are the categories our products must be present in
string[] categoryNames = { "Software", "Support" };
var query = from product in Product.All()
         where product.CategoryProductRelations.Where(x => categoryNames.Contains(x.Category.Name)).Count() == categoryNames.Count()
         select product;

The idea here is to first find all products for the categories we’re looking for. With that done we compare the number of categories found for each product with the number of categories we’re looking for (in our categoryNames array). If they match we’ve got he result we were after in the first place.

The cool thing about this query is that everything is translated to SQL behind the scene so the end result is very efficient execution of the query.

posted on Monday, 22 November 2010 11:59:22 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Wednesday, 17 November 2010

To lead off the documentation on how to build the various pieces of a uCommerce based e-commerce site I wanted to first describe what those components are. Having worked with a multitude of clients and projects in my previous career as an e-commerce consultant I’ve come to take many of these things for granted, but as uCommerce grows in popularity I’ve come to realize that while many has a firm grasp of what an e-commerce project entails others are just starting out with e-commerce for the first time.

Most, if not all, e-commerce solutions consist of the same overall systems as a prelude to documenting how to actually build these systems using uCommerce I’ll outline what they are and which role they play.

This series will cover browse, marketing, checkout, customer service, and order processing.

First up the browse  portion of your webshop project.

Bulk of the Traffic

The customers coming to an e-commerce site start out not as a customer but as casual user of your site trying to find a suitable product for their needs. More than 90% of the traffic coming to your site will take place in the browse pieces with users looking through catalogs, categories, and products so you’ll want to make sure that this piece is as efficient as can be.

Tell the Story

The browse flow is all about telling the story about the products and convincing the user to become a customer. This is where integration between Umbraco and uCommerce comes into the picture because you can use the two to tell a very convincing story indeed using product pages, articles, blog entries, and rich media to grab the user’s interest and engage them to convert.

Shop in Shop

A scenario growing more common is to offer shop in shop functionality in e-commerce sites. It might be a company offering to run the platform for other companies offering each their own store with custom look and feel and even custom checkout flow. This is commonly found in B2B projects.

On the B2C side of things shop in shop is commonly used to give separate brands individual sites, which cater specifically to the target audience of that brand or for putting together micro branding sites for campaign activities. This is the e-commerce equivalent of throw-away marketing sites that you’ve probably done a lot of already.

You’ll also encounter the B2B-B2C combo from time to time. In this scenario the client needs to offer a sites which caters both their B2B customers as well as the B2C customers. Requirements vary wildly between a B2B and B2C site so a nice way to structure such a solution is to simply set up to stores, which might share some of the same products, but pricing will differ for individual customers and one site might require login where the other does not.

Catalog Structure

catalog-bookAn important part of putting together the browse flows is to decide on a catalog structure. Do you need to support international sites? Will they need to have different catalogs with a different range of products?

The nice thing about catalog structure is that you can easily change it or even leave the structure entirely in the hands of your client. What you can’t leave in the hands in your client though is the task of describing the data, which goes into the catalog system AKA establishing the taxonomy of your product catalogs.

One of the very first exercises that you’ll do is try to figure out what a customer means why their talking about their products. Do they need to operate with or without variants? Are they using a combination of products and product families? What information will they need to maintain on the product level? Brand? Supplier? MSRP?

Key Pieces of Information

These are your key pieces of information that as a minimum you absolutely want to display as part of the browse flow: Product name, high resolution images, product description, price, and inventory status.

A nice rule of thumb is that whenever you display any of this information you need to remember to include a “Add to cart” button. After all that’s what we’re here for, right?

Product Listings

7productYou’ll spend most of your time creating various product listings and taking special care that categories are presented in the best way possible.

The simplest product listings are the ones which simply pull products based on the contents of a category, but that’s seldom enough as we discuss in the next paragraph.

Store owners spend a lot for time gathering product data and getting that data shaped into product information ready to present to potential customers. That’s why you’ll spend time creating custom listings based on the information available on each product, e.g. a custom listing which shows the latest additions in the store, all products on sale. This will help automate some aspects of the maintenance in the store.

Catalogs and categories are a great foundation on which to build and you’ll get a lot of mileage out of them if you use them creatively, but if you truly want to make your client happy you need to pay special attention to the automated listings.

Do keep in mind the cardinal rule: Whenever you display product information remember to also display an “Add to cart” button.

The Product Page

I keep wondering why people pay so much attention to the design of “The Front Page”? It seems that in many cases we’re locked into conventional thinking when it comes to web design. “The Front Page is the first page we see, so why not give it special attention?”. It turns out that on the web this is not the case. The front page will actually receive only a tiny fraction of your overall website traffic as close to 80% of incoming traffic will be organic traffic coming from search engines like Google and Bing.

With this in mind every page turns into a landing page on your site in which case it makes sense to focus on the pages that you have a lot off: Product pages.

When creating your product page template you’ll want to keep in mind that this might be the first page that the customer sees thus you can add information which pertains to the overall value of shopping with your online store. Free shipping on everything? 30 return policy? Great, make sure that you say so on every page including the product page, because the customer might be coming here for the very first time.

Of course you need to present the customer with the actual product information as well. Keep in mind the key pieces of information and be aware of the fact that different products might require different presentation. Some products are visually oriented such as jewelry while others are more specification driven like TVs.

If you’re designing a site which will sell a very broad range of products you might need different templates to display product differently based on which type they are. One template might emphasize images and provide a gallery while another might bring the facts out a the primary selling point.

Guided Sales Funnels

Product listings will usually require custom filters for narrowing down the contents of a particular category or specialized category browse flows to enable the user to drill into the catalog by designing a browse flow which tries to anticipate the needs of the customer, e.g. the customer is looking for a shirt, so we might ask her a series of questions which will result in an ever narrower product listing:

Q: “What type of clothing are you looking for?”, A: “Women’s shirts”

Q: “To which occasion will you be wearing the shirt?”, A: “Casual home wear”

Q: “Will you be wearing the shirt inside or outside?”, A: “Outside"

The result might be that we’re displaying women’s fleeces.

The upside of a guided sales flow is that the customer is more likely to convert if we can accurately predict the circumstances which brought her to the site in the first place. The downside is that we might miss the mark completely in which case conversion is unlikely. The solution is simple: Build more guides sales flow and start asking questions at a higher level or be sure to try and grab her interest by displaying other products, which might grab her attention. That where related products come into play.

Related Products

The most common types of related products are your classic upsell-, cross sell-, and others bought relations, but other types of relations might be put into place to further enhance the probability of the macro conversion.

Once a user has decided on a product you’ll want to try and upsell them on an even better version. If you’re anything like me you’ve found yourself looking at one type of TV only to find yourself carrying home a more expensive model either due to a salesman doing his job a tad too well or in some cases because you upsold yourself, in any case that’s the upsell grab the users attention with one product and get them to choose a more expensive version.

You’ll be familiar with the cross sell as well. Sticking with the TV again the cross sell happens when you’re convinced that you need an HDMI cable, batteries for the remote, etc.. With that in place the upsell starts all over on the HDMI cable and the batteries. Round and round it goes.

As with automated product listings “others bought” relations are usually generated automatically, but not always. Sometimes you can get away with maintaining those types of relations manually if the store owner want a high degree of control. Keep in mind that whenever you’re dealing with automatically suggested data users usually want to be able to override the information.

There are a lot of opportunities to use related products for creating a better customer experience and optimizing conversion rates. Take for example a special set of products and display them during checkout or even after on the confirmation page or as part of the order confirmation e-mail.


Search-Engine-MarketingSearch is an area becoming increasingly important to e-commerce sites. The options alone for doing search on an e-commerce site tell us as much. Customers expect to get Google-like results from the search engine on your e-commerce site. A feat which is very difficult to achieve even using something like the Google Search Appliance. The fact is that Google has vast quantities of statistic data available, which can’t be said for a single e-commerce site.

What we do have at our disposal is specific knowledge about the customers expected to come to the site. We can leverage that to adapt the site to the expected needs of the customer like what was described in the previous section dealing with Guided Sales. It also applies to search though as we’re able to create more specialized search experiences as we’ll dive into next.

You’ll usually see the simple- and advanced search. Simple search being your ubiquitous search box at the top of the site. Search suggestions might be a part of this, which enables customers to see possible search results as they type in their query.

What can trip you up is the advanced search as it might vary wildly from site to site. A site like ASOS.com is built with advanced search front and center powering the entire browse flow. More commonly though advanced search will present a bunch of options for the user to fill in and get more refined search results on. This is where your knowledge about the customers coming to the site comes into play as you’ll need to tailor these options to the expected needs of the customers.

Another variation on search is your specification search, which narrows down products in the store by searching for individual specifications one at a time, e.g. Car, Make, Year.

Keep the Customer in the Know

During the entire process it’s important to keep the customer up to date as to what’s going on. Customers these days are fickle and might leave your site for the slightest of reasons so you’ll want to keep their confidence high at all times by presenting them with the information they need when they need it.

Questions commonly posed by potential customers include, “what will shipping cost me?”, “can I have this item quickly?”, “what’s the difference between these similar items?”, “what’s my warranty like if I choose to buy?”, “what’s the return policy like?”.

Wrap Up

That’s it for an overview of the browse piece of an e-commerce site. As you can see browse is much, much more than simply slapping the products from a category onto the screen. The browse flow requires finesse to grab the customer’s attention and even more so to engage the customer further to convert. In your browse flow keep the micro conversion in mind as this persuades the customer to do the macro conversion over time.

When specifying an e-commerce project you’ll want to take special care with areas like advanced search, guided sales funnels, and any dynamic listings requested by the customer as these traditionally will cause you an extra bit of effort, but will pay off handsomely both for you and your client.

posted on Wednesday, 17 November 2010 10:57:31 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Tuesday, 09 November 2010

One of the common questions we get about uCommerce is, “how do I get rid of the Developer Edition banner on my site when I demo for the client?”. Before you get the answer a little background information.


When we designed the uCommerce licensing system one of the requirements was to not get in the way of the developer so we wanted something which kept uCommerce running even though no license is present.

That’s how the uCommerce Development banner came to be and it works great. It’s only displayed when a user accesses the site from an external IP address so you’re free to develop and design your site without it interfering in any way.

But sometimes you really want to be able to demo your site without the banner. Until now the only way to do this was either to keep accessing your site locally, which is impractical if you’re doing onsite demoes for your client, or install a license, again impractical if you’re not ready to go live with the site.

Introducing Unlicensed URLs: Stage, Staging, and Preview

To make your life a little easier we introduced unlicensed URLs with uCommerce version, which are basically a bunch of words that you can add to your domain name to avoid the developer edition banner being rendered as part of your output.

To achieve this you simply set up your domains to include either of the words “stage”, “staging”, or “preview”. Whenever one of these words are found as part of your domain name the banner will not be displayed, e.g. stage.mysite.com, stagemysite.companyname.com, preview.mysite.com, staging.mysite.com will not show the banner.


Wrap Up

Unlicensed URLs are a great way for designers and developers to demo their work without having that pesky banner show up to ruin the day. This way you hold off on acquiring a production license until your client needs to go live with the site.

Please remember that this is only supported by uCommerce and later.

posted on Tuesday, 09 November 2010 09:25:14 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Saturday, 06 November 2010

The Challenge

In some scenarios you want to leave payment processing almost entirely up the remote payment gateway to avoid having to raise the PCI compliance level of your solution. The challenge then becomes to put in place infrastructure to handle the interactions between your server and the payment gateway server both when redirecting the customer to the payment gateway and handling any return traffic from the payment gateway to your server.

Basically the customer is redirected to the payment gateway to enter credit card information and is redirected back to your server once the process is done. Meanwhile the payment gateway will in some cases perform a callback to your server as well to notify you about the status of the payment.


Purchase Flow

These steps will be executed during the payment processing flow. Authorizations, captures, refunds, and voids (cancellation of a payment) are handled by the gateway. Follow the yellow boxes in the picture above.

  1. User arrives at the Store and gets a basket assigned.
  2. The user adds different products to the basket.
  3. User checks out and confirms the basket content.
  4. User types in buyer information (email, address, name, etc.).
  5. User selects a payment provider, e.g. PayPal, SagePay, WorldPay, PayEx, Payer.se, DIBS, or ePay.
  6. Process Payment will either result in a local store flow or a remote payment gateway flow. See the 2 different flows below. The only real difference is how the implementation of the request payment is done.
  7. The user gets directed to a form, which makes an auto postback with Javascript to the gateway with all the required information. This information might be the amount, key, order number, and more depending on the gateway.
  8. User chooses type of credit card.
  9. User types in credit card information.
  10. The payment gateway validates the information. When valid, it will make an asynchronous or synchronous callback back to the shop’s PaymentProcessor.axd (See the description of the class later in this guide). Depending on the payment gateway it will automatically redirect you back to the shop or present you with a “return to shop” button; you can click if you want to return to the shop, to get a receipt.
  11. The user gets an order receipt, optionally CC via email.

The Solution

To solve the problem of the customer leaving the store server to authorize credit cards an extended framework for handling payments is needed, which is used to accomplish the interaction between server in a structured and simple way.

This is a two-step process:

  1. We need to prepare the data to be sent to the payment gateway and then redirect or post that information to the gateway thus handing over the user to the gateway.
  2. Second we need to intercept the callback, so we can mark the payment as completed. If that was the last payment in a series the entire order needs to be marked as completed, usually by executing the checkout pipeline.

Payment Window Framework Explained

The IPaymentWindow is the main interface implemented to support the server to server interaction. It’s implemented by the class ExternalPaymentMethodService, which contains the methods for requesting payments, “RequestPayment”, which will redirect the customer to PaymentRequestForm which in turn redirect the customer to the payment gateway supported by the particular payment method service.

Passing the Customer to the Payment Gateway


Passing the Customer from the Payment Gateway



This class implements the IHttpHandler interface. In a default uCommerce installation its set up by default to intercept calls made to “PaymentRequest.axd”.

What it does
  • Tries to extract payment information from the URL using the PaymentUrlInformation helper class.
  • From the payment information it will try to find the payment in the system.
  • It will then lookup the payment method service assigned to the payment.
  • Cast the payment method service to an IPaymentWindow.
  • Calls RenderPage method on the IPaymentWindow instance just found.



This class also implements the IHttpHandler interface. In a default uCommerce installation it’s set up by default to intercept calls made to “PaymentProcessor.axd”.

As PaymentProcessor is exposed as an HTTP endpoint it is important that all data it receives is validated. For many payment gateways this is done using MD5 hashes of the values passed to the gateway and back or two-encryption as is the case with PayPal.

What is does
  • Tries to extract payment information from the URL using the PaymentUrlInformation helper class.
  • From the payment information it will try to find the payment in the system, which has the status marked as “PendingAuthorization”.
  • It will look up the payment method service used to request this payment as passed in the URL.
  • Casts the payment method service to an “IPaymentWindow”.
  • Calls method ProcessCallback on the IPaymentWindow instance with the payment found earlier as the parameter.


The “IPaymentWindow” represents a class that is able to render a page to the Response or to handle a callback from payment gateways.

  • RenderPage – This method should return a HTML page and return it. The page rendered will usually contain the HTML form, which needs to be posted to the payment gateway to initiate the payment processing flow on the remote end. It can however be used to redirect the user to another URL also. In these cases it will return an empty string.
  • ProcessCallback – This is called from the PaymentProcessor class and handles logic involved when a callback arrives. That could be getting the transaction id, setting the payment status as authorized, things like that.


Interface for implementing a Payment Method Service for payment processing. This interface is part of the ExternalPaymentMethodService. The IPaymentMethod service is documented in detail elsewhere, but holds the most basic interface for doing payment gateway integration like RequestPayment, AcquirePayment, Cancel, and Refund.


This is an abstract base class for building a HTML page as most payment gateways expect a form POST to pass information to the service; this class eases the implementation.

  • BuildBody – Here goes all the HTML elements inside the <body /> tag, this is usually the form elements to represent the data.
  • BuildHead – Here goes all the HTML elements inside the <head /> tag. This is in most cases just used to put some javascript to make the form autosubmit.
What it does

When Build is called it will return the HTML page with the html, head, and body tag and all the custom tags that were added in the two abstract methods BuildHead and BuildBody.



This is the base class when implementing an external payment gateway. Since this class implements the IPaymentWindow, you also need ProcessCallback and RenderPage. See the IPaymentWindow for a description.

Abstract methods

There are three methods that are required to be implemented. Acquire, Refund, and Cancel payment, if the gateway supports it. These are suffixed with internal, because they are protected and are only used by the base class “ExternalPaymentMethodService”.

  • AcquirePaymentInternal
  • CancelPaymentInternal
  • RefundPaymentInternal


Helper classes


Class used when extracting payment information from a URL. This is primarily used by PaymentRequestForm and PaymentProcessor. It extracts information from the HttpRequest instance provided to the “ExtractInformation” method.

The method expects the URL to be in the following format:

· http://yoursite.com/{somedir}/{someotherdir}/{PaymentMethodName}/{PaymentId}/file.axd

· http://yoursite.com/{PaymentMethodName}/{PaymentId}/otherfile.axsd

The '/' is used as the spilt character, so only the imagination will limit you here.



Abstract base class used when working with MD5 hashes. It contains one method to compute a hash from a string usually to validate information sent to the payment gateway and receive back on the local server to ensure that the values aren’t tampered with.



This is the base class for configuration files. It’s a convenient way to store user defined configuration, so it’s possible to change them at runtime instead of having to recompile the assembly.


Steps Required to Build Your Own

  • Configuration - ConfigurationSection
    • Recommended way as you can change settings during runtime.
  • The form builder
    • Create the PageBuilder that implements AbstractPageBuilder class. It contains some helper methods, which will ease the implementation.
  • Payment Method Service
    • Create a class that implements the ExternalPaymentMethodService class.
    • Implement the following abstract methods
      • RenderPage – method called to render the page to the Response stream.
      • ProcessCallback – Process a callback from a payment gateway.
      • CancelPaymentInternal – Gateway specific calls to cancel a payment.
      • AcquirePaymentInternal – Gateway specific calls to acquire a payment.
      • RefundPaymentInternal – Gateway specific calls to refund a payment.
    • Implement the following properties
      • Name – this is the name that is used in the web.config file, when registering the payment method service.

Register the payment method service in the web.config file.

You are now done implementing it and will now be able to select it from the uCommerce interface.



With the Payment Window Framework you have a nice way of creating the server to server interaction without having to do the supporting pieces yourself. More importantly the framework is used in a number of the payment providers supplied with uCommerce out of the box like PayPal, SagePay, RBSWorldPay, PayEx, DIBS, ePay, and Payer.se.

posted on Saturday, 06 November 2010 09:15:33 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Friday, 05 November 2010

When uCommerce was introduced to the world at Codegarden ‘09 one of the things we demoed was how to build simple inventory management using the API and pipelines.

The great thing about pipelines is that they’re very easy to extend so we didn’t think to actually include the inventory tasks; until now that is.

What does it do

The pipeline tasks are pretty simple and do one thing: During checkout one task looks for a field on your product definition called “InventoryOnHand” if found decrements that field with the quantity ordered by the customer. It’s that easy.

Now inventory management wouldn’t be complete if it didn’t support returns as well. So a second task is configured to run as part of the order processing flow in the backend of uCommerce. If an order is moved to a cancelled state the task looks for that same field once more and increments “InventoryOnHand” with the quantities found on each order line.

Setting it up

As mentioned the inventory tasks “DecrementInventoryOnHand” and “IncrementInventoryOnHand” looks for a field called “InventoryOnHand”. So you need to add to your product definitions for inventory management to kick in. You’re free to have the field only on some product and not on others. The tasks will adapt to whatever the case might be.

One thing to note is that if you’re operating with variants you want to add the “InventoryOnHand” field as a variant property otherwise uCommerce won’t pick it up.

If you don’t use variants just leave Variant Property off.


Managing Inventory Levels

With the new field in place you can now manage inventory levels on products or variants as you would any other product property.


Cancelled Orders

The store owner might decide to cancel an order in which case the quantites ordered need to be returned as inventory. IncrementInventoryOnHand handles this for you.



Here’s what the pipelines look like in case you were wondering.

Checkout pipeline


ToCancelled pipeline


Wrap Up

That’s it. With two pretty simple tasks uCommerce now has simple inventory management built right in.

posted on Friday, 05 November 2010 14:50:41 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Monday, 01 November 2010

Any good e-commerce solution lets the store owner stay in contact with customers. One of the most well established ways of doing this is using the tried and true e-mail.

A strength of the integration between uCommerce and Umbraco is that Umbraco is particularly good at building nice looking pages so we thought, “why not use this to build e-mails as well?”, so that’s what we did. The great thing about this approach is that you don’t have to learn some obscure templating language to style your e-mails, you simply build your e-mail content like you would build any other page in your solution using XSLT or .NET user control, whichever suits you the best.

Steps Involved in Sending E-mail

To send e-mail you’ll need to:

  • Add the types of e-mails you’ll be working with in uCommerce
  • Set up a profile for your store to use
  • Configure the actual e-mails and their templates using Umbraco
  • Configure your store to use that profile
  • And finally trigger the e-mail from XSLT, a pipeline, or .NET

Adding a New E-mail Type

uCommerce employs the notion of E-mail Types, which are your basic kinds of e-mails that you’re working with. Out of the box a single type is supplied called “order confirmation”, but you can configure your own types as needed.

Other types might include “Welcome new customer”, “Thank you signing up to the newsletter”, or more business-like type e-mails like “Your items are shipping” or “Invoice”.


To set up a new e-mail type you need to go to Settings => E-mail => Types, right click Types, and click Create.


Add an E-mail Profile

“What’s an E-mail Profile and why do we need one?”, you might ask.

uCommerce supports multiple stores in a single installation and these stores might vary wildly in look and feel so we needed a way to set up multiple instances of the same e-mails on a per store basis to match that same look and feel from store on e-mails across different stores, e.g. an invoice for Store A might have a different look and feel than an invoice for Store B. Thus the notion of an E-mail Profile was introduced to group e-mail instances together for use on individual stores.

As you can see from the screenshot below the profile has an e-mail instance associated per e-mail type created previously. The difference being that for an E-mail Profile we’re dealing with an actual e-mail while an E-mail Type is a placeholder. The system basically ensures that we’re dealing with the same e-mail setup across all stores and makes it easier to deal with in code.

The process of creating a new profile is the same as you just used to create an E-mail Type.


Create the E-mail Content in Umbraco

As mentioned previously e-mail is generated using Umbraco using content nodes, templates, macros, and/or user controls. uCommerce comes with a single Umbraco page out of the box: Order Confirmation, but really you can use any content node in Umbraco.

Each e-mail is language enabled so if you need multiple language variations of your e-mail you can set up a content node for each language you wish to support.


The template of your content node can be used to load information particular to the e-mail you’re sending by using macros. By use of a little magic uCommerce will provide the content page with a query string parameter named “orderGuid”, which will give you context information to load data.

Lets say that we’re building an order conformation e-mail and assume that we’re receiving the order guid in our query string. The code to load data would look as follows:

<!-- The query string param will always be 'orderGuid', but may contain additional parameters like a customer number or product id -->
<xsl:variable name="orderGuid" select="umbraco.library:RequestQueryString('orderGuid')"/>
<xsl:variable name="cart" select="CommerceLibrary:GetPurchaseOrder($orderGuid)"/>
<!-- code for formatting the contents of the $cart variable -->

Configure Contents of E-mail

Going back to uCommerce you need to specify which content node uCommerce is to use when generating the e-mail.

First you’ll set up the basics of the e-mail such as the name the e-mail is coming from and sender address and optionally whether the e-mail is to CC or BCC’d to anyone, e.g. stores owners like to get an e-mail notification when new orders roll in and this is the perfect use case for CC and BCC.


Next up you’ll configure the multilingual pieces of the e-mail like the subject and the contents of the e-mail, which you set up in a earlier step.


Select the template in Umbraco using the content picker. Please note that this might be any content node in Umbraco; OrderConfirmation is used only as an example.


Configure Your Store to use an E-mail Profile

Once you’re happy with the e-mails in your installation you’re ready to tell your store to use those e-mails. To do so go to Product Catalog => <Your Store> and select your E-mail Profile.

With this step completed uCommerce will know which e-mail and template to select when you ask it to send a particular e-mail type in a given store. More on that in the next step.


Send the E-mail

Now you’re ready to tie it all together and send the e-mail to the customer. As with most APIs in uCommerce you can go with either XSLT or .NET when you want to trigger the e-mail. Use whatever makes sense in your particular scenario.

Using XSLT you can use the following to trigger our order confirmation template from before:

<xsl:variable name="orderGuid" select="CommerceLibrary:GetBasket()/purchaseOrder/@orderGuid"/>
<xsl:variable name="result" select="SendEmail('OrderConfirmation', $orderGuid)"/>

The XSLT extension “SendEmail” used above actually uses a class called EmailService to do its thing.

You can leverage this same class in .NET or pipeline yourself with the following code:

// Get the services required for sending e-mails
var emailService = ObjectFactory.Instance.Resolve<IEmailService>();
var localizationContext = ObjectFactory.Instance.Resolve<ILocalizationContext>();
// Find the relevant e-mail profile for the current store
var emailProfile = SiteContext.Current.CatalogContext.CurrentCatalogGroup.EmailProfile;
// Load information for e-mail personalization
var purchaseOrder = SiteContext.Current.OrderContext.GetBasket().PurchaseOrder;
// Set up personalization parameters - params will be passed to
// the configured e-mail template
var queryStringParameters = new Dictionary<string, string>();
queryStringParameters.Add("orderGuid", purchaseOrder.OrderGuid.ToString());
queryStringParameters.Add("customerId", purchaseOrder.Customer.CustomerId.ToString());
// Send e-mail
                    new MailAddress(purchaseOrder.BillingAddress.EmailAddress),

Please note that both examples assume that you’ve added a billing address to the basket prior to sending e-mail. Keep in mind that uCommerce uses standard .NET SMTP to send the e-mail so you will have to configure the SMTP server you want to use in web.config.

As of uCommerce you can use a standard pipeline task to send e-mails. Simply edit the relevant pipeline configuration and add SendEmailTask to the flow. When uCommerce is installed OrderConfirmation is added as a default. If you need to send other e-mail types you see how to configure them by taking a look at /umbraco/ucommerce/Checkout.config.

You can tell uCommerce to send a different type of e-mail by specifying an e-mail type name as shown in the screenshot below. Just replace “OrderConfirmation” with the name of your e-mail type; this is the name that you used when you created your e-mail types in a prior step.


With that you’ve sent your first e-mail with uCommerce.

Wrap Up

The process of sending e-mail with uCommerce does require a couple of steps to get going, however, in return you get the full power of Umbraco as a content management system to fully style your e-mails thus avoiding to have to learn some arcane templating system.

In addition you can even take advantage of some more advanced macros within uCommerce. Think of the value of sending out your order confirmation e-mail, not only with the details of the order, but with added information about related items to each item bought or special offers tailored to the customer.

This is the value of having Umbraco and uCommerce handle your store e-mails.

posted on Monday, 01 November 2010 17:02:38 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback