# Monday, 28 February 2011

To lead off the documentation on how to build the various parts 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 career I’ve come to take many of these things for granted. As uCommerce grows in popularity I wanted to share some of these things in the hopes of making your next e-commerce project a bit smoother.

If you missed the first article in the series called Anatomy of an E-commerce Solution: Browse, which deals with product catalogs and product presentation.

Micro Conversions

imageToday e-commerce stores and webshops are all about enabling store owners to tell their story. While the CMS plays a hugely important role in this area, marketing is another story altogether. Marketing can be divided into internal- and external marketing.

Internal marketing is about setting up special offers for customers to further engage them in the buying process. Too often focus is solely on the the macro conversion, i.e. converting the user to a customer when in reality you need to focus equally on micro conversions, i.e. the act of convincing the user to perform minor conversions with the final goal of getting to the macro conversion.

The most common micro conversion is to offer the user to sign up for a newsletter so you might engage her later on  with direct e-mail communication, but there are many opportunities for micro conversions in webshop like getting them to add more demographic information to their profiles to provide better targeting for site ads and discount, getting them to download sales materiales, or get in touch with a sales representative via e-mail or live chat.

Site Ads

You want the user to navigate to interesting products, so why not throw up a banner advertising for the unique selling points of the products or offer up some additional information about the product like a PDF or video? Or how about letting your users compare products? Banners range from the run of the mill “Buy for x amount and get free shipping” to more advanced banner where you tell the customer exactly what they need to do to get the discount, “Buy for x amount more and get shipping shipping, i.e. the banner is aware of the customer context and shows how much more the customer must buy for the get the discount – a much more actionable banner than the first one.

Social Commerce with Customer Reviews and Ratings

imageOne of the most efficient marketing activities is to let customers do marketing on behalf of the store by enabling them to give ratings and perform full product reviews. Reviews and ratings made by actual people have a very high degree of credibility and many users turn to the reviews section of the product page to find out whether the product is right for them or not.

Indeed research today shows an increasing number of customers not willing to buy products without having consulted product reviews prior to the purchase.

Discounts

At the end of the day store owners need tools to convince the customer to convert. These tools might include incentives like reduced prices, over all discounts on the order itself, or voucher codes. Discounts come in many shapes and forms and are usually grouped in campaigns, which run for a certain amount of time after which they are removed from the site. In other words we’re dealing with temporary pricing and benefits.

Your most common types of discounts include “buy two for one”, “percentage off the order”, “amount off the order”, “volume discount”, “free shipping”, and more.

Vouchers and Gift Cards

Vouchers and gift cards are a certain type of discount which be paired with individual products, entire categories, or just the vanilla stand alone voucher. They enable store owners to pass out codes which can be used during checkout to receive a discount. Vouchers are a very effective means of converting the customer or getting repeat business from existing customers.

Vouchers are often used as a means of increasing the effectiveness of external marketing by including voucher codes with e-mail marketing campaigns, in print media, or on billboards.

Gift cards are basically a variation on the voucher with the main difference being that we’re not really dealing with a discount anymore as a customer will pay full price for the privilege of using the

Targeting

imageWith ads and discounts in place you’ll want to target customers with your message. For that purpose targeting is often used. Basically targeting will enable a store owner to configure who should be exposed to a particular message and determine when a discount should be triggered for a customer. Targeting often works by collecting information about the anonymous user on the site: Which products did she look at during the visit, which ones are displayed right now, what was the entry point into the store, any search terms which brought her to the store in the first place.

These are the basics, but often you’ll go a step farther and start building a profile about a given customer. By categorizing content and products the profile will be become more complete over time and as that happens targeting will become ever more precise to the point where the anonymous customer can be placed in a segment.

Once the customer logs in the profile will often be carried over and the store owner will know even more about the particular customer. A scary example of this in practice is Amazon, which it seems will pick up which products you look at and some days later will send a targeted e-mail to you offering a special on…. exactly the products you viewed.

Scary and brilliant at the same time. The mechanics are pretty straightforward when you think about it.

External Marketing

External marketing include all the activities which drive new traffic to your site including search engine optimization, search engine marketing, link building, social marketing, etc.. While support for some of these activities can be characterized as convenient others must be supported directly in the platform for your solution to rank highly. These include the ability to add custom meta data to your products, have pretty URLs laden with search terms, having product reviews formatted using one of the micro formats that Google recognizes to display as part of search listings.

Content is king in this matter. You can optimize all you want, but in the end getting incoming links to the store by having great content is what really counts. And it’s more interesting to create too.

Common Pitfalls

One surprise I’ve had far too often when shopping online or dealing with existing webshops is customers getting a discount by accident. By accident I mean the case where customers are never told about the discount until they’re in the check out flow and notice a lower price than what was listed. Store owners who do this sort of thing might as well toss money in the toilet – it’s more fun and would yield the same profit at the end of the day. The customer didn’t know about the discount, she would have bought the product anyway so why bother having a discount at all?

It’s crucial to remember that marketing is not about lowering pricings or giving great discounts it’s about getting the message out. If you don’t get the message out you might as well not bother.

Summary

I’ve only started to scratch the surface of what marketing in an online store or webshop entails, but these are some of the scenario that you’ll be expected to support in your e-commerce solution. Some of it is pretty srraightforward to build, other areas not so much. The area which will trip you up is typically the management pieces and targeting of content and discount. These are areas which either require very efficient workflows or complicated logic to achieve.

Check out the first article in the series called Anatomy of an E-commerce Soltion: Browse, which deals with product catalogs and product presentation.

posted on Monday, 28 February 2011 13:50:35 (Romance Standard Time, UTC+01:00)  #    Comments [1] Trackback
# Thursday, 10 February 2011

One of my favorite features of uCommerce is the extensible framework lurking underneath the surface. Using the framework you have the opportunity to add, modify, or even completely the out of the box functionality of uCommerce. Shipping methods are no exception to this rule. Specifically you can build custom shipping method services to enable custom calculation of shipping costs during the checkout flow as discussed in Shipping Methods Explained.

This article covers adding a new shipping method service to uCommerce and having it show up the admin UI like so.

SNAGHTML9d935c

The Framework

Before you get into the nitty gritty of building your first custom shipping method service you’ll need a little background about the surrounding framework to understand what’s going on. Your shipping method service first needs to be configured in uCommerce via web.config (more on that later), once written the uCommerce pipelines will make sure and trigger your service when appropriate. By default shipping methods services are triggered in the Basket Pipeline by the task called CalculateShippingCostForShipments. If you’re interested in more information about pipeline please see the uCommerce Pipelines Explained article.

Notice that the tasks ends on Shipments plural. uCommerce supports multiple shipments per order and will call the proper shipping method service for each shipment based on the shipping method selected for it.

image

Pretty simple stuff. Now for the fun part: Writing your own shipping method service.

The IShippingMethodService Interface

image

This interface is what uCommerce uses to be able to calculate shipment costs. As you can see from the code it’s pretty simple. Basically you’ll receive the shipment as created using either the XSLT or .NET API and you’ll have the opportunity to loop through the relevant order lines, which are linked from the shipment. Lets see what’s involved to create a simple volume based IShippingMethodService.

Volume Based Shipping Method Service

Volume and weight based shipping pricing are probably the most common shipping scenarios for an online store so lets try and build one of them as an example. First you’ll need to create a new Visual Studio project and add a reference to the UCommerce.dll assembly. You will also need a reference to the Subsonic.Core.dll assembly. With that in place you’re ready to start implementing the service.

The Methods and Properties

image

As you can see you just need to implement two methods and a single property to get it going. The names of the methods should make it fairly obvious what they’re for. ValidateForShipping might require some explanation. As discussed in Shipping Method Explained each shipping method can be configured to available only to certain stores and for shipment only to certain countries. The ValidateForShipment enforces these rules. If you just need an unrestricted shipment you can go ahead and always return true, but be aware that users might be confused if they set up a shipping method in one way but it doesn’t actually check for the conditions thus behaving differently from what they expect.

CalculateShippingPrice Method

First up lets calculate the shipping price for the shipment:

public Money CalculateShippingPrice(Shipment shipment)
{
    // First sum up the total weight for the shipment.
    // We're assumning that a custom order line property 
    // was set on the order line prior when the product was added to the order line.
    decimal totalWeight = 0;
    foreach (OrderLine orderline in shipment.OrderLines)
        totalWeight += orderline.Quantity * Convert.ToDecimal(orderline["Weight"]);
 
    decimal shippingPrice = 0;
    if (totalWeight > 10)
        shippingPrice = 100;
    else if (totalWeight > 20)
        shippingPrice = 200;
    else
        shippingPrice = 300;
 
    // To instantiate a new Money object we need the currency,
    // which is set on the purchase order. To get the currency
    // we move through Shipment -> OrderLines -> PurchasrOrder -> Currency
    return new Money(shippingPrice, shipment.PurchaseOrder.BillingCurrency);
}

Of course the business rule in this particular case is very simplistic, but you get the idea.

ValidateForShipping Method

Next up is the ValidateForShippingMethod, which is actually called prior to CalculateShippingPrice to validate that the shipping method is validate for the current purchase order. The SinglePriceShippingMethod which comes out of the box has rules to ensure that the shipping method has a shipping address set and that the shipment is set to be delivered to one of the allowed countries for the shipping method.

public bool ValidateForShipping(Shipment shipment)
{
    if (shipment.ShipmentAddressId <= 0)
        throw new InvalidOperationException("Cannot validate shipment for country. Remember to set the shipping address for shipment.");
 
    var shippingMethod = shipment.ShippingMethod;
    if (shippingMethod == null)
        throw new InvalidOperationException(
            "Cannot validate destination country for shipment. It does not contain a shipping method. Remember to add a shipping method to your shipment before validating.");
 
    return ValidateShippingDestination(shipment.OrderAddress,
                                shippingMethod);
}
 
/// <summary>
/// Validates the order lines according to their desired destination and configured contries for shipping method
/// </summary>
/// <returns></returns>
protected virtual bool ValidateShippingDestination(OrderAddress shippingAddress, ShippingMethod shippingMethod)
{
    var eligibleCountries = shippingMethod.GetEligibleCountries();
 
    // No eligible countries exist - so the shipment isn't valid
    if (eligibleCountries == null) return false;
 
    return eligibleCountries.SingleOrDefault(x => x.Country == shippingAddress.Country) != null;
}

Name Property

I probably should have started out with the easier of the member to implement, but Name ended up with the shortest straw and got to go last. Name will be set externally based on the name used when the shipping method service is configured in web.config, which incidentally is the next topic of this article.

public virtual string Name
{
    get;
    set;
}

VolumeShippingMethodService

With the name property implemented our VolumeShippingMethodService looks like this:

public class VolumeShippingMethodService : IShippingMethodService
{
    public Money CalculateShippingPrice(Shipment shipment)
    {
        // First sum up the total weight for the shipment.
        // We're assumning that a custom order line property 
        // was set on the order line prior when the product was added to the order line.
        decimal totalWeight = 0;
        foreach (OrderLine orderline in shipment.OrderLines)
            totalWeight += orderline.Quantity * Convert.ToDecimal(orderline["Weight"]);
 
        decimal shippingPrice = 0;
        if (totalWeight > 10)
            shippingPrice = 100;
        else if (totalWeight > 20)
            shippingPrice = 200;
        else
            shippingPrice = 300;
 
        // To instantiate a new Money object we need the currency,
        // which is set on the purchase order. To get the currency
        // we move through Shipment -> OrderLines -> PurchasrOrder -> Currency
        return new Money(shippingPrice, shipment.PurchaseOrder.BillingCurrency);
    }
 
    public bool ValidateForShipping(Shipment shipment)
    {
        if (shipment.ShipmentAddressId <= 0)
            throw new InvalidOperationException("Cannot validate shipment for country. Remember to set the shipping address for shipment.");
 
        var shippingMethod = shipment.ShippingMethod;
        if (shippingMethod == null)
            throw new InvalidOperationException(
                "Cannot validate destination country for shipment. It does not contain a shipping method. Remember to add a shipping method to your shipment before validating.");
 
        return ValidateShippingDestination(shipment.OrderAddress,
                                    shippingMethod);
    }
 
    /// <summary>
    /// Validates the order lines according to their desired destination and configured contries for shipping method
    /// </summary>
    /// <returns></returns>
    protected virtual bool ValidateShippingDestination(OrderAddress shippingAddress, ShippingMethod shippingMethod)
    {
        var eligibleCountries = shippingMethod.GetEligibleCountries();
 
        // No eligible countries exist - so the shipment isn't valid
        if (eligibleCountries == null) return false;
 
        return eligibleCountries.SingleOrDefault(x => x.Country == shippingAddress.Country) != null;
    }
 
    public string Name
    {
        get; set;
    }
}

Registering Your ShippingMethodService with uCommerce

Your custom shipping method service needs to configured with uCommerce so users are able to set up new shipping methods which use your code. This happens in web.config. When uCommerce is rolled out a number of configuration sections are added to web.config one of which called ordersConfiguration.

<ordersConfiguration>
    <shippingMethodServices>
        <add name="SinglePriceService" type="UCommerce.Transactions.Shipping.SinglePriceShippingMethodService, UCommerce" />
        <add name="VolumeShippingService" type="MyUCommerceApp.VolumeShippingMethod, MyUCommerceApp" />
    </shippingMethodServices>
    <paymentMethodServices>
        <add name="DIBS" type="UCommerce.Transactions.Payments.DefaultPaymentMethodService, UCommerce" />
    </paymentMethodServices>
</ordersConfiguration>

With the web.config updated you’ll now be able to select your new shipping method service in the UI:

image

Summing It All Up

Creating your own shipping method service to handle custom calculations takes as little effort as implementing two methods and a property. Once it’s registered with uCommerce users take over and set up the shipping method to their liking. Becuase your shipping method service is rolled into a separate assembly it’s very straightforward to share between projects.

If you’d lie more information about Shipping Method please take a look at the article Shipping Methods Explained.

posted on Thursday, 10 February 2011 22:26:29 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback

imageThe wonderful world of shipping is truly a tangle of complicated business rules and pricing. At uCommerce we realized this long ago thus we do not try to supply every single shipping method known to man in the box. Rather we built a framework to allow you, dear developer, to build to specification whatever you need. Indeed this is at the very core of our Framework First methodology.

The Shipping Method

A shipping method in uCommerce consists of two discrete parts: data for presenting the shipping method to the customer and calculating costs and logic to calculate costs based on whatever is in each shipment for an order. uCommerce supports multiple shipments per order and your shipping method will have the opportunity to calculate different shippings costs based on whats in each shipment.

As you can see in the screenshot above a shipping method contains a bunch of different information.

Common Tab

image

All the base information for your shipping method like the name, which will be used in code as well as on shipments created with this particular shipping method.

The default payment method in cases where your shipping method is also a payment like Collect on Delivery.

For developers the Service drop down list is of particular interest as this is where you can hook into the shipping system with your own code to calculate shipping costs. More on that in a separate article.

Access Tab

image

When running a multi store set up it’s often handy to be able to set up different shipping methods for different stores and determine which countries each shipping method is available to ship to. The access tabs lets you do just that.Pricing Tab

Pricing Tab

image

Here you’ll set up the pricing for your shipping method. By default each shipping method can have individual pricing in each price group, which means that you differentiate pricing in multi currency scenarios or even for individual customers if they’re working with individual price groups. The pricing strategy can be overridden by creating a custom shipping method service, which is covered in another article.

Multilingual Tabs (English)

image

The final tabs covers the multilingual capability of uCommerce. Most areas in the admin UI will have multilingual tabs assigned to them. uCommerce will pick of the configured languages in Umbraco and display a multilingual tabs for each of them where appropriate. For shipping methods this means that you can set up information about each shipping method to match whatever language your customers speak.

Summing It All Up

As you’ve seen uCommerce shipping methods are very straightforward to set up. You can have multiple shipping methods configured and you decide which stores each of the shippings method are available to. For each shipping method you can either use the out of the box shipping providers or you can roll your own to match customer requirements exactly.

You might also be interested in reading Building a Custom Shipping Method Service for Calculating Shipping Costs.

posted on Thursday, 10 February 2011 20:59:43 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Friday, 17 December 2010

When you delete something in uCommerce it doesn’t really go away. Rather uCommerce employs soft deletes on various data objects, particularly in the catalog, to enable you to query historical data. e.g. for reporting purposes.

Some times however you’d like to clear test data from your catalogs and you need to get a little heavy handed to do it by going directly to the database and deleting the data.

Of course you have to observe the relations between existing data and delete in the proper order to avoid breaking constraints in the database. The uCommerce product is a rather complex collection of tables, which hold your custom properties, language variations, prices, relations to other catalog items such as other products and categories, which means that getting it right might be a little tricky.

image

Fortunately we already did the script for you and it goes a little something like this:

-- PLEASE NOTE: If you run this script against your uCommerce database all products and related data will be deleted.
-- There's no way to get it back unless you keep a database backup handy.
BEGIN TRANSACTION
DELETE FROM uCommerce_PriceGroupPrice
DELETE FROM uCommerce_ProductRelation
DELETE FROM uCommerce_CategoryProductRelation
DELETE FROM uCommerce_ProductProperty
DELETE FROM uCommerce_ProductDescriptionProperty
DELETE FROM uCommerce_ProductDescription
DELETE FROM uCommerce_Product
COMMIT TRANSACTION
posted on Friday, 17 December 2010 11:09:01 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Wednesday, 01 December 2010

The basic process of updating uCommerce from one version to another is straightforward when you’re running a default setup: You install the new package on top of the existing one and uCommerce will figure out what needs to be migrated.

Database updates are handled automatically and will roll you forward without incident. XML files on the other hand are a little more tricky to merge so instead of trying to merge them uCommerce will overwrite existing config files with newer versions to ensure that the config matches the rolled out binary version of uCommerce; exactly as Umbraco does. This means that If you customized any of the uCommerce configuration files you will have to reapply those changes.

Not to worry though uCommerce will back up the files before resetting them. You’ll find the older versions sitting next the orignal file with a .backup extension.

Most of the time getting your settings back is a simple matter of copying back the backed up version of your configuration files and you’re done. The steps for manually reregistering your settings are outlined below.

image

Web.config

Web.config is an interesting file because it’s used by Umbraco and uCommerce itself. During installation uCommerce merges its configuration with the existing web.config contents preserving any settings not owned by uCommerce, i.e. Umbraco, .NET, basically anything not known by uCommerce.

Connection Strings

During install the Umbraco connection string is picked up and added to the uCommerce configuration section to enable running uCommerce in a separate database. If you’re running with a separate database you need to point uCommerce at the other database once the update is complete.

SNAGHTML3968cdd

Payment Method Services

Any custom payment method services for integrating payment gateways need to be registered in web.config. If you’ve created your own payment method service you’ll have to remember to reregister it once the update is complete. If you’re using the built-in ones you can omit this step. It’s important that you use the same name for your custom payment method service when you reregister it.

Payment method services are found in the <commerce> <ordersConfiguration> <paymentMethodServices> section in web.config.

image

Individual Payment Method Service Configurations

Each payment method service built into uCommerce comes with a configuration file. As these files are rolled out as part of the standard package install process they’re overwritten when you install a newer version of uCommerce. As with any other file you’ll find your old version of the file sitting next to the new one with a .backup extension.

image

Pipelines

Pipelines are basically XML configuration files which control the tasks executed in each pipeline and the order of execution as well. If you’ve added your own pipeline tasks to the standard uCommerce pipelines Basket, Checkout, ToCompletedOrder, ToCancelled, or SaveOrder you’ll have to add your custom tasks again after updating.

You’ll find the pipelines in the /umbraco/ucommerce/pipelines folder.

image

Components.config, Presenters.config, and XmlRenderings.config

All major components of uCommerce are configured in a central XML file, which lets you override any of the default uCommerce behavior by configuring your own components. While this is not the most common extension point used you’ll still have to reregister your custom components if you’ve extended uCommerce in this fashion.

Also web.config contains a reference to components.config in the <commerce> <runtimeConfiguration> which has to point at the correct file.

Presenters.config and XmlRenderings.config are referenced by Components.config and contains config for the UI pieces of uCommerce. Specically the backend (Presenters) and the frontend (XmlRenderings).

Wrap Up

uCommerce makes it very easy to update an existing installation provided that you’re running with a standard configuration. There are a couple of things you need to be aware of if you’ve customized the standard configuration files. This check list will make it easy to ensure that you didn’t miss anything when you update your existing site with a newer version of uCommerce.

posted on Wednesday, 01 December 2010 14:14:29 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Tuesday, 30 November 2010

uCommerce comes with built-in support for SagePay payments. This guide will walk you through getting uCommerce to work with SagePay for payment processing. uCommerce integrates with SagePay using server integration.

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 “SagePay”.

image

Click the newly created node and select “SagePay” 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 done click “Save”.

image

That’s everything in the uCommerce interface.

Settings in SagePay Administration Panel

You can learn more about how to configure SagePay in the SagePage Help Centre.

Editing SagePay.config

Now we need to edit the SagePay.config file.

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

image

Finding vender

Vendor is the name you use when you login with SagePay.

image

Finding debug

Debug mode indicates whether you want to have an intermediate page show up with the values, which will be posted to the payment gateway.

Finding testmode

Testmode indicates whether your site is in simulation mode (SIMULATOR), test mode (TEST),  or running in production mode (LIVE).

Finding successUrl

URL the customer is redirected to once the payment is accepted.

Finding abortUrl

URL the customer is redirect to if she cancels payment authorization.

Finding FailureUrl

URL the customer is redirect to if the payment could not be authorized.

Finding notificationUrl

uCommerce will generate a callback URL for internal use. Leave the setting at (auto) unless you need to handle callbacks yourself.

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 “SagePay” 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 = 'SagePay'

or just edit it manually in SQL Server Management Studio.

image

Now the default pipeline 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.

ToCancelled.config

image

ToCompletedOrder.config

image

FAQ

  • Testmode – Make sure test mode if turned off when going live.
posted on Tuesday, 30 November 2010 10:26:11 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback

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

Authorization is available for all plans with RBS WorldPay. If you wish to acquire (capture) or refund payments you need to mail: support@rbsworldpay.com and ask them to setup “Remote Admin”. At the moment it’s not possible to cancel an authorization with the “Remote Admin”.

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 “WorldPay”.

image

Click the newly created node and select “Worldpay” 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 done click “Save”.

image

That’s everything in the uCommerce interface.

Settings in WorldPay Administration Panel

Changes needed in the WorldPay administration panel, so it will work with uCommerce. Make sure when you are logged in that you are in “Production” mode or else you want to able to save the changes. If you can see the “Switch to Test” link on the picture below, you are in “Production” mode.

image

Edit Payment Pages

This out of scope for this guide, however World Pay offers lots of possibilities for customizing the results pages. You can read more about it here.

image

Instant capture

In Denmark it is not allowed to capture a payment before the order is shipped, so we need to turn this off. This can different in other countries.

Settings

· “Off” means you need to manually capture the payment.

· “0” Means instant capture.

· “1-14” are delay in days before the capture happens.

Changing the setting

· Click “Profile” in the menu to the left.

· Click “Configuration Details”

· Capture Delay: Set the value as accordingly.

· Click “Save”

image

General changes to the account

  1. In the menu to the left click “Installations” and you should get a list like the one below.
  2. Then click the “Edit” button that are on the same line as the text: “Select Junior”, this is the primary account.

image

Settings

  1. Payment Response URL.
    • Put the following text there without the quotes: “<wpdisplay item=MC_callback>”
  2. “Payment Response enabled?
    • Make sure it’s checked.
  3. Payment Response failure email address.
    • Write your email address here, if you want to receive email notifications, when an error occurs with the “Payment Response”
  4. Check the option “Attach HTTP(s) Payment Message to the failure email?” if you want detailed information attached to the email.
  5. Payment Response password.
    • A password of your choice. In the next section this is referred to as the “callbackPW”, please take a note of this.
  6. MD5 secret for transations.
    • Custom text of your choice. But less than 32 characters. This is referred to as the “Signature” in the next section, so please take a note of it.
  7. SignatureFields
    • Type the following text below without the quotes, or you will get an “Invalid MD5” signature when trying to make a authentication.
    • “instId:amount:currency:cartId:MC_callback”
  8. Click “Save” and you are done in this section.

WorldPay-control-panel

Editing the Worldpay.config File

Now we need to edit the WorldPay.config file.

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

image

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

Finding debug

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

Finding testMode

Set this value to “True” when testing the integration with WorldPay. When going live set this value to “False”.

Finding instId

Click “Profile” in the menu. The “instId” is the number (normally 6 digits) in the red cirkel.

image

Finding callbackPW

This is the “callbackPW” from the previous section.

Finding callback

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

Optional: Finding remoteInstId and authPW

Click the “Profile” link in the menu to the left. Then you will see a screen like the one below.

  1. This is the remoteInstId and is normally 6 digits.
  2. This is the authPW, random digits and letters

image

Finding instantCapture

True/False weather instant capture is On or Off. If you choose “Off” in the instantCapture in the previously section, this values needs to be “False” otherwise “True”.

Finding key

This is just a text string of your choice. Recommended is just using random digits/letters.

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 “WorldPay” 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 = 'WorldPay'

or just edit it manually in SQL Server Management Studio.

image

Now the default pipeline 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.

ToCancelled.config

image

ToCompletedOrder.config

image

FAQ

  • Testmode – Make sure test mode if turned off when going live.
  • I get the error message “Cannot find an available route for the purchase. This may be caused by merchant configuration or remote systems failures.”
    The error messages might mean a number of different things. One of the meaning that we encountered during test is that our transaction amounts were greater than GBP 5,000.
  • Acquiring a payment and immediately cancelling the same payment moves the order to “Requires Attention”
    RBS WorldPay employs a queuing system for handling payments which means that when uCommerce asks WorldPay to acquire a payment we immediately get back a response which indicates that all went well, but in actuality the transaction is queue for acquire on their end.
    If a transaction is cancelled immediately after the state on the uCommerce end is different from RBS WorldPay thus an error message is logged in the following form: “Refund failed >> N,-1,PMPPI.invalidStatus”.
posted on Tuesday, 30 November 2010 09:34:23 (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# 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”.

image

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

clip_image002[4]

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

clip_image003[4]

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

clip_image005[4]

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.

clip_image006[4]

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.

clip_image008[4]

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

clip_image009[4]

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.

clip_image010[4]

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.

clip_image012[4]

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.

ToCancelled.config

clip_image014

ToCompletedOrder.config

clip_image016

FAQ

· 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”.

image

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

image

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.

image

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

image

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.

image

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.

image

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

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