# Wednesday, April 10, 2013

imageIn some cases though you might need to leverage the API outside a web context for automated integration between systems, for custom web services, or integration of uCommerce functionality directly in other custom applications such as point of sale- or kiosk apps.

This article outlines the steps required to get the API going for uCommerce 3.

Running uCommerce 2? Please refer to Enable the uCommerce E-commerce API Outside the Web Context instead.

Create New Console Application Project

Open Visual Studio and create a new console application project in the usual way. We’ll use that as a basis for getting the APIs up and running.

My usual project structure has a folder for the project source and any libraries required to build it like below.

image

Copy uCommerce Assemblies to Project

You’ll find the assemblies in your website under /bin.

Copy the following assemblies to /lib in your project.

  • Castle.Core
  • Castle.Windsor
  • FluentNHibernate
  • Iesi.Collections
  • log4net
  • NHibernate.ByteCode.Castle
  • NHibernate.Caches.SysCache2
  • UCommerce
  • UCommerce.Infrastructure
  • UCommerce.Pipelines
  • UCommerce.Transactions.Payments
  • UCommerce.Presentation
  • UCommerce.Umbraco
  • interface
  • umbraco
  • businesslogic
  • ClientDependency.Core
  • Umbraco.Core


image

Copy the Configuration and Pipelines Folders to the Project

You’ll want the core configuration and the pipelines as part of your project to be able to use the API fully.

Copy these folders to the project folder of your solution.

image

To project:

image

Include Configuration and Pipelines in Project

image

Set Configuration and Pipelines Folders to Copy to Output Folder

For uCommerce to able to pick up the configuration they need to be copied to the output folder of the compiled application.

Select all the config files and press F4 to bring up the properties for the files.

Set “Copy to Output Directory” to “Copy if newer”.

image

Reference the Assemblies in Your Project

Next reference the assemblies you copied to the /lib folder in Visual Studio.

image

Modify App.Config

Next up we need to modify the application config with settings to enable the final bits of uCommerce to run.

Open up web.config of your Umbraco site and locate the configSections element. Copy the sectionGroups called “commerce” and “systemcache” to the coonfigSections element of App.config.

<sectionGroup name="commerce" 
type="System.Configuration.ConfigurationSectionGroup">
<section name="syscache" 
type="NHibernate.Caches.SysCache.SysCacheSectionHandler, 
NHibernate.Caches.SysCache2" requirePermission="false" />

Finally we need the actual sections from web.config copied to app.config.

<commerce>
<syscache>

 

With all that in place your App.config file should look like this:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
   <sectionGroup name="commerce" type="System.Configuration.ConfigurationSectionGroup">
       <section name="catalogConfiguration" type="UCommerce.Infrastructure.Configuration.CatalogConfigurationSection, UCommerce.Infrastructure" />
       <section name="runtimeConfiguration" type="UCommerce.Infrastructure.Configuration.RuntimeConfigurationSection, UCommerce.Infrastructure" />
       <section name="securityConfiguration" type="UCommerce.Infrastructure.Configuration.SecurityConfigurationSection, UCommerce.Infrastructure" />
       <section name="amazonPaymentMethodService" type="UCommerce.Transactions.Payments.Amazon.Configuration.AmazonPaymentMethodServiceConfigurationSection, UCommerce.Transactions.Payments" requirePermission="false" />
       ...
      </sectionGroup>
    <section name="syscache" type="NHibernate.Caches.SysCache.SysCacheSectionHandler, NHibernate.Caches.SysCache2" requirePermission="false" />
  </configSections>
 
  <commerce>
    <runtimeConfiguration enableCache="false" cacheProvider="NHibernate.Caches.SysCache2.SysCacheProvider, NHibernate.Caches.SysCache2" connectionString="(auto)" />
    <catalogConfiguration defaultCultureCode="en-US" enforceCategoryNameUniquenessWithinCatalogs="true" />
    <securityConfiguration enable="true" />
    <amazonPaymentMethodService configSource="umbraco\ucommerce\configuration\payments\Amazon.config" />
    ...
  </commerce>
 
  <syscache>
    <!-- Cache catalog objects for 60 mins before refreshing -->
    <cache region="CatalogFoundation" expiration="3600" priority="5" />
    <cache region="MarketingFoundation" expiration="3600" priority="5" />
    <cache region="SecurityFoundation" expiration="3600" priority="5" />
  </syscache> 
</configuration>

Modify Connection String

Finally you need to point the connection string at your database. Simply replace the (auto) values with an actual connection string and you’re good to go.

<runtimeConfiguration ... connectionString="server=(local);database=Umbraco;user id=umbraco;password=1234567890" />

Summary

Leveraging uCommerce outside a web site makes for some interesting use cases. Foremost is automated integration with other systems, but you could use this method to establish an offline Point of Sale or Kiosk-type system with a completely different frontend done in Windows Presentation Foundation for a rich in store experience.

posted on Wednesday, April 10, 2013 4:36:31 PM (Romance Daylight Time, UTC+02:00)  #    Comments [0] Trackback
# Wednesday, October 17, 2012

At uCommerce we’re fortunate in many ways: We get to build products that customers actually use and love and most importantly we get to work with some pretty amazing people.

What we didn’t see coming is the amount of excitement and involvement in uCommerce from our partners and customers. From helping out in the support forums, building extensions, providing key insights and feedback for uCommerce, blogging about uCommerce, to creating full open source projects around uCommerce.

The involvement is truly amazing to see and we want to recognize the people who go above and beyond and thus 2013 is the year for a grand new tradition: uCommerce MVPs (uCommerce Most Valuable Professionals).

How To Become An MVP

uCommerce MVPs are a small, select group of the professionals in the uCommerce community, outliers with the ability to highlight solutions and helping out in the community making the community a better place for everybody.

We select MVPs from the community in a very unscientific way each year in October based on their contributions. Once selected the MVP title is good for the coming year and will be reviewed each year.

MVPs are honored with the “king” Hoptimist to proudly display in their desks :)

Hoptimist-yellow

Sounds like something for you? Here are some pointers if you’d like be considered for MVP next year:

  • If you do something cool with uCommerce blog about
  • Help out in the uCommerce forum
  • Do a talk for your local user group
  • Host a uCommerce code camp
  • Build a package for Umbraco using uCommerce
  • Share your uCommerce extensions like payment providers, shipping providers, etc.
  • Make some noise about uCommerce :)

And now for the most important part of this post: The uCommerce MVPs for 2013.

Tim Gaunt, The Site Doctor, UK

Avatar-Tim-Drinking-Tea

Tim has been around the uCommerce community from the very beginning. He initially got on board after Codegarden 09 when we introduced uCommerce 1.0 and has since been active in the uCommerce community; blogging, providing valuable feedback for uCommerce itself, and recently with his heavy involvement in the development of Avenue Clothing, the new Razor store. He even came up with the name Avenue Clothing :)

His company The Site Doctor builds amazing uCommerce stores. The work TSD does is second to none.

Christian Wendler, Byte5, DE

Christian Wendler, Byte5

Christian popped up in the community in 2011 with his company byte5 immediately producing high quality stores with uCommerce.

His insights and willingness to help out in the Germany with community activities are remarkable, but his work on the uCommerce Data Types for Umbraco package is really what puts him over the top.

In Summary

uCommerce MVPs are a great asset for the community as a whole. With the 2013 MVPs we’re recognizing the first uCommerce MVPs ever who have gone above and beyond in making the uCommerce community a better place.

We’re proud and honored to work with these people!

posted on Wednesday, October 17, 2012 8:27:11 AM (Romance Daylight Time, UTC+02:00)  #    Comments [0] Trackback
# Sunday, May 13, 2012

tomboy-128uCommerce is designed to run in one of two scenarios: Standalone or integrated. When running in an integrated scenario you’ll typically need to import information from other systems like SKUs, preexisting accounts, etc..

If you need to import large amounts of data from external systems you’ll want to the stateless API uCommerce provides for just this type of scenario.

You can skip the background portion if you’re just looking for the quickest way to import data into uCommerce. If not read on and get the inside scoop on uCommerce data access.

Background

uCommerce uses NHibernate for data access a handy way of querying the underlying database and converting the relational data into the e-commerce objects you know and love.

To provide a more convenient way of working with the data access APIs NHibernate will build up a large map of every object ever loaded into memory, which is awesome for caching scenarios and for figuring out which objects require updates and in which order when a write command is issued to the data access engine, but not so much for bulk imports.

As it turns out this is not really what you want for bulk scenarios as the object map tends to slow down writes quite a bit after only a few database operations. This slows bulk import scenarios quite noticeably; even a few hundred write commands.

Luckily you have at your disposal an API optimized for bulk import scenarios called the stateless API.

The Stateless API

The stateless API is named so because it doesn’t maintain the memory map of objects, which is exactly what we want for bulk imports because generally we’re just inserting and updating each object once. We don’t really need L1 or L2 caching, nor identify map tracking and that good stuff.

Using the stateless API offers awesome performance for writes compared to the default one, but it does come with a couple of drawbacks as well, which means there are a couple of areas you’ll have to handle yourself:

  • Lazy loading child collections is disabled
  • ModifiedBy, ModifiedOn, CreatedBy, and CreatedOn properties are not automatically updated
  • Cascades for saves and deletes are disabled
  • Auto soft delete is disabled – everything is deleted permanently
  • Save is disabled and replaced by manual Insert/Updates operations

Fear not the rest of the article describes how to accomplish these operations in a straightforward manner.

First things first: To use the stateless API you need an implementation of ISessionProvider, which is obtained with the following code:

ISessionProvider sessionProvider = ObjectFactory.Instance.Resolve<ISessionProvider>();
IStatelessSession statelessSession = (sessionProvider as SessionProvider).GetStatelessSession();

With the session you’re ready to start issuing commands to the data access layer in a stateless fashion.

Eager Loading Child Collections

By default uCommerce will automatically load any child collections you access, which is very convenient when you want something up and running rapidly. This capability  however is not available when working with the stateless API, so you’ll have to initialize any collection you need manually.

QUICK TIP: This is actually the way to get the best level of performance from your queries too.

Here’s how you eager load order lines for a purchase order.

var purchaseOrder = statelessSession
    // The Query method is an extension method found in the NHibernate.Linq namespace
    .Query<PurchaseOrder>()
    // The fetch method receives a lambda which tells if which child collection to initialize
    .Fetch(x => x.OrderLines)
    // You can use ThenFetch to initialize subsequent child collections on the same parent
    .ThenFetch(x => x.OrderAddress)
    // Loads the first parent
    .SingleOrDefault(x => x.OrderNumber == "WEB-001");

The code above will issue one query batch to the database instead of opening and closing a connection for each round trip as is the case for lazy initialization, so much more efficient all around.

Updating ModifiedOn, ModifiedBy, CreatedBy, CreatedOn Properties

These properties are required by objects implementing the IAuditCreatedEntity and IAuditModifiedEntity. You just need to make sure that they are set for any objects you insert.

Handling Delete Cascades

When you delete an object which has relationships with other objects using the default API uCommerce will handle removing or updating the related objects, e.g. PurchaseOrder.Delete() also deletes associated order lines, customer, addresses, etc..

With the stateless API, however, you have to delete the objects yourself in the correct order to avoid foreign key constraint errors in the database. It works exactly as if you’re deleting directly from the database using T-SQL.

This means that for our order from before you’ll have to delete the order lines and customer before deleting the parant order, which both the order lines and the customer a link to in the underlying data structure.

using (var transaction = statelessSession.BeginTransaction())
{
    var purchaseOrder = statelessSession.Query<PurchaseOrder>()
        .Fetch(x => x.OrderLines)
        .ThenFetch(x => x.OrderAddresses)
        .ThenFetch(x => x.Customer)
        .ThenFetch(x => x.Payments)
        .ThenFetch(x => x.Shipments)
        .SingleOrDefault(x => x.OrderNumber == "WEB-001");
    
    // Issue a delete for each shipment
    // The ForEach method is just for convenience
    purchaseOrder.Shipments.ForEach(x => statelessSession.Delete(x));
    
    // Issue a delete for all child objects of order until they're all deleted
    
    // Finally delete the order itself
    statelessSession.Delete(purchaseOrder);
 
    transaction.Commit();
    
}

Handling Saves

With the default API uCommerce will figure out whether to insert or update an object when you issue a save. This is not the case with the stateless API so you’ll have to issue an insert or update depending on whether you’re updating an existing object or adding a completely new one.

using (var transaction = statelessSession.BeginTransaction())
{
    // Update an existing order
    var purchaseOrder = statelessSession.Query<PurchaseOrder>()
        .SingleOrDefault(x => x.OrderNumber == "WEB-001");
 
    purchaseOrder.ModifiedBy = "Søren";
    purchaseOrder.ModifiedOn = DateTime.Now;
 
    // Save to the database
    // Notice the explicit use of Update for
    // the existing object
    statelessSession.Update(purchaseOrder);
 
    // Create a new order
    var newOrder = new PurchaseOrder();
    newOrder.CreatedOn = newOrder.ModifiedOn = DateTime.Now;
    newOrder.CreatedBy = newOrder.ModifiedBy = "Søren";
    newOrder.BillingCurrency = statelessSession.Query<Currency>()
        .Single(x => x.ISOCode == "EUR");
    
    // Save to the database
    // Notice the use of Insert for the new object
    statelessSession.Insert(newOrder);
 
    transaction.Commit();
}

Handling Soft Deletes

Some entities are marked with the ISoftDeletable interface, which indicates that they never really disappear from the database. The stateless API will permanently delete data from the database. If you want to preserve soft delete behavior you just have to set the “Deleted” property to “true” on objects which have it and issue a save like above.

In Summary

While there are some aspects you have to manually handle when using the stateless uCommerce API for bulk updates it’s still a convenient way to stay in the object oriented world while keeping decent write performance.

Of course all the uCommerce information is stored in standard SQL tables so you can just as well use a tool like SQL Server Integration Services, which bypass the API completely and go straight to the database. This is by far the fastest way to import, but bear in mind that integrations done directly against the database might break when you upgrade to newer versions of uCommerce.

posted on Sunday, May 13, 2012 11:03:55 PM (Romance Daylight Time, UTC+02:00)  #    Comments [2] Trackback
# Wednesday, March 21, 2012

In many cases we come across companies who operate a separate discounting system from their e-commerce platform. In these cases it’s convenient to be able to import external campaigns into uCommerce via code.

This article outlines how you can create campaigns, campaign items, and associated advertising and discounts from code.

If you’re unfamiliar with uCommerce Marketing Foundation you can watch a quick video tour on uCommerce.tv.

Also before you continue you might want to take a look at Marketing Foundation Explained: Targeted Advertisements and Discounts, which explains the terminology of uCommerce Marketing Foundation and Extending Marketing Foundation- Adding A New Advertise and Act Target, which deals with added new targets and awards to Marketing Foundation.

A Bit Of Background

A discount in uCommerce requires a couple of moving parts to get going:

  1. A campaign to group marketing activities aka campaign items
  2. A campaign item to aggregate targets and awards
  3. One or more targets to determine when the campaign item is displayed to the customer, e.g. Customer is looking at the Clothing category
  4. One or more targets to determine when an award is triggered, e.g. Buy for more than 400€
  5. One or more awards, e.g. 10% off unit price

Let’s dive into each of the points individually.

Adding a Campaign

All of the classes below are available from the UCommerce.EntitiesV2 namespace found in the UCommerce.dll.

// Create a campaign to group campaign items
var campaign = new Campaign
                {
                    Name = "My Awesome Custom Campaing",
                    StartsOn = DateTime.Now,
                    EndsOn = DateTime.Now.AddDays(30),
                    Enabled = true
                };
 
campaign.Save();

Adding a Campaign Item

Campaign items require a definition, which determines which fields are available as part of it. We’re using the default campaign item definition in this case, but you can add your own with the fields and multilingual fields matching your requirements. You can learn more about definitions in Catalog Foundation Explained: Product Definitions.

Also worth noting is the “AllowNextCampaignItems” property, which is a way to tell uCommerce to stop evaluating campaign items if the current one is awarded to the customer. This is handy if you wish to limit the number of discounts awarded to the customer. Marketing Foundation Explained: Targeted Advertisements and Discounts describes this in more detail.

// Find a definition for the item to determine which fields are available
var definition = Definition.SingleOrDefault(x => x.Name == "Default Campaign Item");
 
// Create the campaign item to tie targets and awards to
var campaignItem = new CampaignItem
                {
                    Name = "Summer offers",
                    Enabled = true,
                    Definition = campaignItemDefinition,
                    AllowNextCampaignItems = true
                };
 
// Add campaign item to our campaign
campaign.AddCampaignItem(campaignItem);
campaign.Save();

Adding a Target for Advertise and Act

There a many different types of targets you can use. In this case it’s a product target, but you could go with “ProductCatalogGroupTarget” to target a specific store, “ProductCatalogTarget” to target a specific catalog, “CategoryTarget” to targat a specific category, “VoucherTarget” to require a specific voucher- or promo code, “OrderAmountTarget” to target a specific order total, etc. You get the idea :)

It’s important to note that if a target you need is not built-in you can extend uCommerce with your own targets as described in Extending Marketing Foundation- Adding A New Advertise and Act Target.

“EnabledForDisplay” and “EnabledForApply” determines whether the target is used for advertising, act, or both.

// add a product target
var productTarget = new ProductTarget
                {
                    CampaignItem = campaignItem,
                    Sku = "100-000-001",
                    VariantSku = "001", // this guy is optional
                    EnabledForApply = true, // use it for Act
                    EnabledForDisplay = true // use it for Advertise
                };
 
productTarget.Save();

Adding an Award

Here we’re using a discounted unit price award, but again there a many different types of awards you can add like AmountOffOrderTotalAward, AmountOffOrderLinesAward and so on. Remember if the award you’re looking for is not there you can extend uCommerce with your own types.

// Add a unit price discount award
var amountOffUnitPrice = new AmountOffUnitAward
                {
                    CampaingItem = campaignItem,
                    AmountOff = 10
                };
 
amountOffUnitPrice.Save();

Summary

One of the best features of uCommerce is that everything you can do from the UIs you can do from code. This enables developers to do some awesome automated things with uCommerce and it doesn’t take a whole lot of code to do either.

In the article we discussed how to create new campaigns, add marketing activities to them in the form of campaign items, and configure those campaign items with targets and awards to set up actual customer discounts.

posted on Wednesday, March 21, 2012 10:47:56 AM (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Thursday, March 15, 2012

imageA great tool for converting a customer is to display items they’ve previously looked at. One way to do it is by using persistent baskets, i.e. the basket contents remain the same even if a customer leaves and later returns to the store.

But what about the cases where the customer didn’t actually put anything in the basket, but we still want to be able to show some of the items she browsed recently?

Approaches

The most obvious approach is to store SKUs in a cookie and present that list to the customer, but it makes for some pretty trivial use cases down the road, so let’s explore a different way of doing it: A custom basket.

uCommerce comes with the ability to handle as many baskets per customer as you like so why not leverage this to create almost a wish list-like scenario. After all the recently browsed list is just a list of products that sure sounds like a basket?

Creating a New Basket

First up we need to create a new basket. By default uCommerce will do one default basket where every item goes into, but we’ll need a second basket, which we can maintain ourselves.

Let’s do a little Razor, which will create that custom basket and tie it to the customer using a cookie:

   1: @using UCommerce.Runtime;
   2: @using UCommerce.EntitiesV2;
   3: @using System.Web;
   4:  
   5: @{
   6:   ProductCatalogGroup catalogGroup = SiteContext.Current.CatalogContext.CurrentCatalogSet;
   7:   ProductCatalog catalog = ProductCatalog.All().Single(x => x.Name == SiteContext.Current.CatalogContext.CurrentCatalogName && x.ProductCatalogGroup == catalogGroup);
   8:   
   9:   Guid basketId = Request.Cookies["viewedProductsList"] != null ? new Guid(Request.Cookies["viewedProductsList"].Value) : Guid.Empty;
  10:  
  11:   PurchaseOrder viewedProductsList = basketId != Guid.Empty 
  12:                                         ? PurchaseOrder.All().SingleOrDefault(x => basketId != Guid.Empty && x.BasketId == basketId)
  13:                                         : new PurchaseOrder();
  14:  
  15:   // Initialize new order
  16:   if (basketId == Guid.Empty)
  17:   {
  18:     viewedProductsList.OrderStatus = OrderStatus.Get((int)PurchaseOrder.StatusCode.Basket);
  19:     viewedProductsList.ProductCatalogGroup = catalogGroup;
  20:     viewedProductsList.BillingCurrency = catalog.PriceGroup.Currency;
  21:     viewedProductsList.BasketId = Guid.NewGuid();
  22:     viewedProductsList.CreatedDate = DateTime.Now;
  23:  
  24:     HttpCookie cookie = new HttpCookie("viewedProductsList", viewedProductsList.BasketId.ToString());
  25:     cookie.Expires = DateTime.Now.AddDays(30);
  26:     Response.Cookies.Add(cookie);
  27:   }
  28: }

Adding a Product To The List

Once we have the custom basket set up we’ll just start adding items to it in the usual manner from the product page or whenever you deem that the customer showed enough interested to have a product on the recently browsed list.

   1: // Add product being displayed
   2: Product product = Product.All().Single(x => x.Sku == "100-000-001" && x.VariantSku == "003");
   3:  
   4: viewedProductsList.AddProduct(catalog, product, 1);
   5:  
   6: viewedProductsList.Save();

Displaying The Recently Browsed Items List

The third and final piece is to display the list. The code will basically have to look up the cookie tying the list to the customer, load the basket with contents, and display individual order lines to the customer. Simple stuff and here’s how to do it:

   1: @using UCommerce.EntitiesV2;
   2: @using System.Web;
   3:  
   4: @{
   5:   // Find the cookie containing the basketId
   6:   Guid basketId = Request.Cookies["viewedProductsList"] == null 
   7:                     ? Guid.Empty
   8:                     : new Guid(HttpContext.Current.Request.Cookies["viewedProductsList"].Value);
   9:  
  10:   // Load the list
  11:   PurchaseOrder viewedProductsList = basketId != Guid.Empty 
  12:                                 ? PurchaseOrder.SingleOrDefault(x => x.BasketId == basketId) 
  13:                                 : new PurchaseOrder();
  14: }
  15:  
  16: @foreach (var orderLine in viewedProductsList.OrderLines.OrderBy(x => x.Quantity))
  17: {
  18:     <h3>@orderLine.ProductName</h3>
  19:     <p>Bought @orderLine.Quantity times.</p>
  20: }

In Summary

We took a look at what it takes to maintain a separate custom basket for handling a recently browsed items type list. Using a custom basket instead of storing SKUs in a cookie has the added advantage of the extra information available when displaying the list to a customer.

Best of all it takes a trivial amount of code to get it up and running.

The code above sorts the list by quantity; the premise being that the product will have its quantity increased every time the customer looks at it thus we have a handy mechanism for determining the most popular items on the list. You can expand this to look at last modified dates on order lines to see when the customer was last interested in the product and so forth.

Finally the technique outline here is handy for scenarios like gift registries, wish lists, standard recurring orders, and other cases which require a custom list of products maintained either by the customer herself or by the store.

posted on Thursday, March 15, 2012 12:06:46 AM (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Tuesday, March 06, 2012

In this series of articles we discuss the various methods of integrating with payment gateways; in particular how various payment gateways handle integration with hosted payment forms.

In this article we take a closer look at the most commonly employed integration method for payment gateways. Gateways like Authorize.Net, PayPal, WorldPay, Ing Bank (iDEAL), Payer, DIBS, and ePay all use this method for initiating payment using a hosted payment form.

If you’re interested in more background before proceeded please take a look at Intro to Payment Gateway Archetypes.

What Makes An "Outbound User Post"

image

The "Outbound User Post" is the most common archetype we've come across; indeed this is the model we originally designed our payment gateway integration framework to support.

The premise is the HTTP post with a twist: The gateway expects an HTML form to be generated on the store end, which in turn issues a HTTP post to the payment gateway accomplishing two goals in one go:

  1. Payment details such as currency, amount, etc. are sent to the gateway
  2. Customer is redirected to the payment gateway's hosted payment form

The upshot  is that it's pretty simple to work with as it relies solely on HTTP; as such it can readily be integrated using pretty much any technology. All you need to do is get the target URL for the post and the predefined form values right and you're good to go.

More Is Less

image

As it turns out combining the submission of information and the redirect as the sole integration point requires the form to be sent to the customer's browser and submitted from there by the customer herself.

The general purpose payment framework generally has two options for handling this type of integration:

A) Displayed Form, which displays actual information such as the final order confirmation to the customer, or

B) Transparent Form carrying only the required payment information without displaying any details to the customer, which is auto posted to the gateway.

Next up we’ll take a closer look the two options for handling integration.

Displayed Form

forms

The displayed form is essentially embedded on a page displayed to the customer; generally speaking the last page displayed before handing over control to the payment gateway. The form contains predetermined values for amount, currency, and all the other required information to get the payment process going.

The issue obviously becomes one of dealing with ensuring that all the required values are present and named according to the specification and to avoid having to redo the same form over and over again.

In a scenario where a designer or developer control what is displayed to the customer this approach can become quite tricky to handle, i.e. the classic e-commerce "confirm order and proceed to payment" page.

Generally speaking getting this right is a huge part of getting the integration working. As it turns out this is cumbersome at best and downright daunting at worst unless you do this sort of integration work on regular intervals.

Building the form from scratch seems to be what the payment gateways requiring the "Outbound User Post" integration model had in mind when they designed it.

Transparent Form

image

The second option is an auto generated transparent form, which has no other purpose than to carry the payment information required by the payment gateway. It will never be displayed to the customer, but rather transparently be submitted to the payment gateway.

To achieve a transparent redirect JavaScript is required to auto submit the form on behalf of the customer. Most sites out there today require JavaScript to even function properly, which makes it a reasonable assumption to build a framework on.

The upside is very tight control over the payment information sent to the payment gateway and essentially allows a general purpose payment framework deal with the payment without concern for the actual store pages; as such it comes pretty close to being a "real" web service.

In turn designers and developers have an easier time building the store frontend as payment is handled almost as a pure web service although the intermediate form is still there albeit transparently so.

In Summary

The "Outbound User Post" archetype seems archaic in the assumptions made for the integration model. It's simple, yes, but either requires developers integrating using it to completely redo the integration form for each online store or introduce intermediate forms to achieve a transparent integration model.

The uCommerce e-cpmmerce platform handles the outbound user post via a standard transparent form, which is injected into the checkout flow, sent to the customer, and submitted transparently, seamlessly handing over control of the checkout flow to the payment gateway.

The observant customer will notice an intermediate page displayed for a fraction of a second before being handed over to the page gateway.

Surely there must be a better way. It is so happens there is. Read on a discover "Outbound Placeholder".

posted on Tuesday, March 06, 2012 11:05:32 PM (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Sunday, February 26, 2012

payment-gateway-flow

At uCommerce we come into regular contact with payment gateways of all shapes and sizes. At the time of writing this post we're up to fifteen separate payment gateway integrations.

With so many integrations under our belt I realized that we inadvertently developed ad-hoc archetypes to describe the various types of gateways.

When dealing with a new payment gateway the archetypes let us quickly determine which type of gateway we're dealing with and what the requirements will be for integration with it.

This is the first in a series of article describing the various archetypes we've found so far.

A Little Background

Print

Back in the day there was just one way of integrating with a payment gateway: Good old direct API call. The premise was simple; call a remote API with credit card details  entered on your website and get a "yay" or "nay" response back from the gateway with some transaction details. Forms were easy to design, integration was straightforward. All was good in the land of online payments.

Along comes the Payment Card Industry Data Security Standard (PCI DSS), a combined effort between VISA, Mastercard, American Express, Discover, JCB aimed at increasing security around online payments. All good, right?

It did in fact manage to increase security, but increased the complexity integrating with payment gateways as well. “But how?”, you might ask.

Online stores would no longer be able to store or even have customers enter credit card information on their websites without a costly certification of the operating environment.

As a result the payment form found a new home away from home: Payment gateways started offering hosted payment forms to overcome the requirement for the PCI certification. Thus the hosted payment forms were born.

What Sets the Gateways Apart

stand-out

The authorization process and more specifically authorization using a hosted payment form is really what sets payment gateways apart today. It turns out that APIs for acquiring, voiding, and refunding are pretty much all based on the same principle: Direct API integration based on tokens issued during authorization.

It seems that payment gateways all came up with their own variation over the  same theme for dealing with hosted payment forms. No standard exists for handling the process although archetypes have emerged over time as we discovered.

Before we dive into the archetypes let's take a look at why the hosted payment form exists and why so many online stores are using it today.

The Hosted Payment Form

Hosted Payment Form

The primary reason for introducing the hosted payment form was, as we discussed previously, to avoid handling credit card information locally on the online store's own servers. The responsibility is handed over to the gateway.

This makes hosted payment forms great for avoiding security issues with credit card information and generally speaking is the way to go for online stores large and small. Depending on the gateway the hosted payment form allows for the same flexibility as the direct integration combined with a local payment form method so it's really a win-win situation.

What's the Downside

some-assembly-required

Integrating a hosted payment form is generally more tricky. There are more concerns in the way payment information such as amount due is transmitted as many of the available solutions require that information to be submitted by the customer herself to the gateway.

Commonly the process works like this: The online store sends payment information to the customer's browsers, which in turn submits that information to the gateway.

When information is passed to the customer and then on to the gateway a huge can of worms concerning tampering with the payment information is opened up. What's to stop the customer from changing the amount to a big fat zero and getting their order for free?

Thus the total sum of required moving parts to make hosted payment work is increased making for a more complex integration model, e.g. redirects between multiple servers, encryption of payment information, and secure processing of payment gateway responses; more commonly known as callbacks.

Outbound vs. Inbound

in-out-arrowsWhen figuring out which archetype a payment gateway we're dealing with we need to consider two aspects: The outbound call and the inbound callback.

It's important to note that when using outbound/inbound we're looking at the process from the point of view of the online store, i.e. the customer is outbound from the store to gateway and vice versa.

The outbound call deals with passing the customer and relevant payment information from the store to the payment gateway.

The inbound call deals with passing the customer back from the payment gateway along with the all important "yay" or "nay" for the status of the transaction.

In Summary

Hosted payment forms offer tangible benefits over direct API integrations when it comes to security and in some cases flexibility like when dealing with additional security features like 3D Secure.

The benefits come at the price of a more complex integration model, which seems to have as many variations as there are payment gateways.

Despite this we decided to make hosted payment forms the default for built-in payment providers in uCommerce to minimize requirements for online stores running our software.

Hence archetypes evolved because we have a very real need for terminology to enable us to easily talk about the gateways.

posted on Sunday, February 26, 2012 11:05:23 PM (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback
# Monday, February 13, 2012

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

With the Ogone payment provider you can do authorization of payments, instant acquire, acquire and perform refunds both via our automatic uCommerce solution and manually via the back-end office of your Ogone subscription.

Settings in uCommerce

Add a new payment method, under “uCommerce à Settings à Orders à Payment Methods”, by right clicking the “Payment Methods” leaf and use “Create”. You can use any name you like; I have used “Ogone”.

clip_image001

Now we’re ready to configure your new payment method. Click the newly created node and select “Ogone” in the Service drop down list and select “Checkout” in the pipeline drop down list. Remember to fill out the rest of the required information in the rest of the Tabs.

When you’re done, click the save icon. That’s everything in the uCommerce interface.

clip_image002

Settings in Your Back-end Office at Ogone

First you need to log in with your “pspid” and password.

clip_image004

Click “Technical information” at the menu to the left of the page. At the center screen 7 tabs is displayed. Use the settings as used on the screenshots representing each tab.

1. Global Security Parameters

Set the first hash algorithm to SHA-1 as our system uses this hash algorithm for payment requests and maintenance requests.

Set the character encoding to the first option.

clip_image006

2. Data and origin verification

You need a password in this field. This password is used in the communication between your uCommerce shop and Ogone payment provider for security reasons. This pass phrase is used when the system requests a payment at Ogone.

The password must follow rules given by Ogone. Press the blue information button for information regarding those rules.

clip_image008

3. Transaction feedback

The first four URLs in the “http redirection in the browser” section can be left blank, as we configure this in our configuration file later on.

The next step is to link from the secure payment page to your page which processes the payment.

Please note that “/<PARAMVAR>/PaymentProcessor.axd” is required at the end of your URL.

clip_image010

Next step is to tell Ogone which parameters they need to send back to our site. There’s quite a few available, just select them all. This is a good idea as that information is logged, should any problem occur, problem solving is made a lot easier.

clip_image012

The last part in this section is to put in the SHA-OUT pass phrase. This is the same method as before but for security reasons you should use another phrase this time.

When Ogone makes the callback to our server, this pass phrase is used in a hash algorithm in order to test for corrupt requests.

Now we need to make an “admin without user management” but with access rights to make direct link requests.

Click Users at the back end office menu to the left and click new users in that section.

clip_image014

clip_image015

Fill out the required fields and put your PSPID password in the password field and click create. At the next page you’ll get a password.

Now we need to change the password to something that doesn’t contain special characters (use “a-z” and/or “0-1”.

clip_image017

Under the password section, simply select the user you’ve just created and put in the old password and together with the new you want and click submit.

This is it in the back-end office at your configuration.

Configuring Acquire and Cancel Payments

The Ogone payment provider comes with the ability to do automatic acquire and cancel payments. In order to make this work you need to enable a pipeline task.

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

clip_image018

Simply remove “<!-- “ and “-->” at the highlighted line. These are HTML comment sections.

Configuring the “Ogone.config” File

Now we need to edit the ”Ogone.config” file in order to match your environment.

You’ll find the configuration file at “rootdir\umbraco\UCommerce\Configuration\Ogone.config” where rootdir is the location on your computer, where Umbraco is installed.

Some values need to be found in the back-end office. All of those can be found under technical information.

clip_image003

Parameter list for the configuration file:

Parameter name

Value

pspid

The pspId of your Ogone account.

Find it at the bottom of the menu to the left at the back-end office.

Userid

The Userid of the user you’ve just made.

Password

The password for the user you’ve just made.

acceptUrl

The URL the customer is redirected to after an accepted payment.

cancelUrl

The URL the customer is redirected to after a canceled payment.

backUrl

The URL the customer is redirected to if the customer clicks the back button on the payment page.

declineUrl

The URL the customer is redirected to if the payment is declined.

exceptionUrl

The URL the customer is redirected to if a problem occours in the payment process .

All the urls are a local webs in your website such as “yourshop.com/orderconfirmation.aspx”.

Debug

Tells the system weather this is in debug mode. This should be set to false.

shaSignOut

The shaSign used when Ogone redirects to the payment processor.

Under technical information, go to the bottom of the “transaction feedback” tab to find the SHA-OUT pass phrase

shaSignIn

The shaSign used when your uCommerce website requests a payment at Ogone.

Under technical information, go to the “Data and origin verification” tab to find the SHA-IN pass phrase

language

Must follow the right language codes otherwise it’s set to the default value “en_US”.

instantAcquire

Is set to “true” if you want instant acquire.

Is set to “false” if you want to only authorize a payment.

testMode

Tells the system weather this is in test mode. This should be set to false.

Congratulations - your website now includes payments with the Ogone payment provider.

posted on Monday, February 13, 2012 4:47:18 PM (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback

uCommerce comes with buil-in support for MultiSafepay. This guide will walk you through getting uCommerce working with MultiSafepay for payment processing.

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

clip_image001

Click the newly created node and select “MultiSafepay” in the Service drop down list. Choose Checkout ast he pipeline. 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

That’s everything in the uCommerce interface.

Settings in MultiSafepay back office.

Create a back office at MultiSafepay with the MultiSafepay Connect.

Create a new website under Setttings -> Sites.

clip_image004

Category

Choose the category your site belongs to

Description

Can be anything, just a name you give your website.

Base URL

The URL for your website

Notification URL

clip_image006

MultiSafepay notifies uCommerce about new payments and changes to existing payments using the notification URL. The URL you receive notifications from MultiSafepay will be in the format https://www.mystore.com/id of your payment method/PaymentProcessor.axd

To find the PaymentMethodId you need to search the database. If you used the name “MultiSafepay” for the payment method name, you can run this SQL query in the SQL Server Management Studio:

select PaymentMethodId from uCommerce_PaymentMethod where Name='MultiSafepay'

A sample URL for a payment method with an ID of 10 would be https://www.mystore.com/10/PaymentProcessor.axd

PrivatePay

An option so MultiSafepay won’t give you information regarding the consumer. Name and address will be excluded.

SecondChance

Should the consumer cancel midway, they will receive an email giving them a second chance to complete the process.

Editing the MultiSafepay.config file

Now we need to edit the MultiSafepay.config file.

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

image

TestMode

If set to “True” the MultiSafepay test site will be used, not their live site. If not testing, this should be set to “False”.

Account Id

Your account ID from the MultiSafepay back office. (See picture below)

SiteId

The ID provided by MultiSafepay when creating a new site. (See picture below)

SiteSecurityCode

The SiteSecureCode provided by MultiSafepay when creating a new site. (See picture below)

CallbackUrl

Leave setting at (auto) unless you want to handle callbacks yourself.

Accept

The URL you return to when completing a payment.

CancelUrl

The URL you return to when cancelling a payment.

Click Settings è Websites to find the screen below.

clip_image009

MultiSafepay back office

In the MultiSafepay back office you have options to refund and cancel, this cannot be done without using the MultiSafepay back office.

clip_image011

Use the green refund button to start a refund or the red cross to cancel a pending payment.

Please note that any changes to a payment in the back office will cause a notification to be sent to uCommerce. The notification will cause uCommerce to update the status of the order the payment belongs to to “Requires Attention”.

posted on Monday, February 13, 2012 4:43:08 PM (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback

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

With iDEAL (ING) only authorization with instant acquire is available. To cancel or refund a transaction you will have to use the iDEAL (ING) Dashboard. This is implemented with iDEAL (ING) Basic.

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 “iDEAL (ING)”.

clip_image002

Click the newly created node and select “iDEAL (ING)” 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_image003

That’s everything in the uCommerce interface.

Settings in iDEAL Dashboard

Changes needed in the iDEAL (ING) Dashboard, so it will work with uCommerce.

Configure Secret Key

On the Menu on the left side, click “Signup process –> Configuration”. Make sure that there is a key in the “Secret key” field and the click “Start upload”. The “Certificate upload successful” should be marked with a green sign upon success.

clip_image005

Configure Return URLs

uCommerce performs validation of the payment information when iDEAL (ING) performs the callback. To get the callback, for verify the payment, you need the set the “Notification” to XML and the “Notification URL” to you shops URL ending with “/PaymentMethodId/PaymentProcessor.axd”.

To find the PaymentMethodId you need to search the database. If you used the name “iDEAL (ING)” for the payment method name, you can run this SQL query in the SQL Server Management Studio:

select PaymentMethodId from uCommerce_PaymentMethod where Name='iDEAL (ING)'

The URL could be then end with: “/10/PaymentProcessor.axd”.

clip_image007

Click “Start Upload” when you are done.

Editing the Ideal_Ing.config File

Now we need to edit the Ideal_Ing.config file.

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

clip_image009

Some of the below information are found in the iDEAL (ING) Dashboard, so start by logging in you aren’t already.

Finding secretKey

On the Menu on the left, click “Signup process” –> “Configuration”, here you will find the secretKey. Make sure that the “Certificate upload successful” is marked with a green sign, before you use it.

clip_image011

Finding merchantId

On the Menu on the left, click “Signup process” –> “Application”, here you will find the Merchant ID.

clip_image013

Finding subId

Unless agreed otherwise with the acquirer, you should use “0”(zero).

Finding successUrl, cancelUrl and errorUrl

To get the customer redirected back to your page after the payment is completed, you have to specify a return URL depending on payments result: Success, Error and Cancel.

Finding debug

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

Finding testMode

Test mode will toggle the payment method service to use a test environment where applicable. Usually this implies working against another URL.

Valid values “true” or “false”.

Finding language

Set preferred language, currently only “Dutch”(nl) is supported by remote gateway.

Excecuting 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, open Umbraco click “Commerce” select the payment method (“iDEAL (ING)”). In the pipeline drop down list select Checkout and then click “Save”.

clip_image014

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.

Configuring Auto Acquire and Cancel Payments

Authorize.Net comes with the ability to do automatic acquire and cancel payments. In order to make this work you need to enable a pipeline task.

To enable auto acquire edit the “ToCompletedOrder” pipeline.

To enable auto void/refund edit the “ToCancelled” pipeline.

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

clip_image015

Simply remove “<!-- “ and “-->” at the highlighted line. These are HTML comment sections.

FAQ

  • Test mode – Make sure test mode if turned off when going live.
  • You can simulate different payment statuses by using special amount on your payment. Please note that success payments can only be made with a payment total of 1 EUR.

Transactions made with any other amount than the ones below will result in an error:

    • Successful transaction: 1 EUR in test mode
    • Cancelled transaction: 2 EUR in test mode
    • Expired transaction: 3 EUR in test mode
    • Open transaction: 4 EUR in test mode
    • Format error: 7 EUR in test mode.
posted on Monday, February 13, 2012 4:37:11 PM (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback

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

With the Google Checkout you can do authorization of payments, acquire payments, refund and cancellation of payments both via uCommerce and the back end office of your Google checkout subscription.

Settings in uCommerce

Add a new payment method, under “uCommerce à Settings à Orders à Payment Methods”, by right clicking the “Payment Methods” leaf and use “Create”. You can use any name you like; I have used “Google Checkout”.

clip_image001

Now we’re ready to configure your new payment method. Click the newly created node and select “Google Checkout” in the Service drop down list and select “Checkout” in the pipeline drop down list. Remember to fill out the rest of the required information in the rest of the Tabs.

When you’re done, click the save icon. That’s everything in the uCommerce interface.

clip_image002

Settings in Your Google Checkout Back-end Office

First you need to log in to your back end office at: https://sandbox.google.com/checkout/sell/settings?upgrade%3Dtrue&hl=da&nui=1&ltmpl=seller

Now click integration in the left panel. You should get to a page looking like this:

clip_image004


API Callback URL

In the API callback URL: you need to put “http://yoursite.com/10/PaymentProcessor.axd”.

You’ll need to replace “10” in the URL with another number that we’re going to find now.

Open “Microsoft SQL Server Manangement Studio” and log in to the database for your site.

Open a new query document by clicking the “New Query” button.

clip_image006

Write this line:

SELECT PaymentMethodId FROM uCommerce_Paymentmethod where name = 'Google Checkout'

and then click the execute button.

You’ll now need to replace the number the management studio gives you with the number “10” in the URL.

Callback Contents

Now set the radio button at the callback contents to: Notification as XML.

API Version

The API Version must be set to “Version 2.5”

Notification Filtering

The notification filtering must be checked

Configuring Acquire and Cancel Payments

Google Checkout comes with the ability to do automatic acquire and cancel payments. In order to make this work you need to enable a pipeline task.

To enable auto acquire edit the “ToCompletedOrder” pipeline.

To enable auto void/refund edit the “ToCancelled” pipeline.

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

clip_image007

Simply remove “<!-- “ and “-->” at the highlighted line. These are HTML comment sections.

Configuring the “GoogleCheckout.config” File

Now we need to edit the ”GoogleCheckout.config” file in order to match your environment.

You’ll find the configuration file at “rootdir\umbraco\UCommerce\Configuration\ GoogleCheckout.config” where rootdir is the location on your computer, where Umbraco is installed.

Parameter list for the configuration file:

Parameter name

Value

merchantID

This is the identification of your google checkout account. When logged in at: https://sandbox.google.com/checkout/sell/settings?upgrade%3Dtrue&hl=da&nui=1&ltmpl=seller

Find it at the top right corner of the page.

merchantKey

This is a passphrase needed in the communication between your shop and google checkout.

Find it on the integration page in the back end office at “Google Checkout”, at the right side of the page.

successUrl

This URL redirects your customer back to a specific page at your site after a successful authorization.

editBasketUrl

This URL redirects your customer to the basket on your site.

testMode

Tells our system weather the application is in test mode or not. This must be set to false.

debug

Tells our system weather the application is in debug mode or not. This must be set to false.

clip_image009

 

clip_image010

FAQ

Ensure that uCommerce uses the same currency as your Google Checkout seller account

During our test of Google Checkout we found that transactions made with currencies other than the main currency of the seller account will always result in rejected authorizations. If you create the seller account with GBP please make sure that any test transactions are made with the same currency.

Failed transaction will appear with the message ”Cancelled by Google: Payment declined” in the seller account and the messages ”Cancelled” and ”Your order has been cancelled.” in the buyer account.

Please note that this applies to the sandbox only.

Ensure that “testMode” is set to “true” when using the Google Checkout sandbox for testing

If your GoogleCheckout.config is set to testMode=”false” Google Checkout will return HTTP code 400 bad request when accessing sandbox. Make sure that you’re operating in test mode when calling the sandbox.

posted on Monday, February 13, 2012 4:33:38 PM (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback

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

At the moment, the eWAY API only supports instant payment, which means that refunds or cancel payments is not possible.

Settings in uCommerce

Add a new payment method, under “uCommerce à Settings à Orders à Payment Methods”, by right clicking the “Payment Methods” leaf and use “Create”. You can use any name you like, I have used “EWay”.

clip_image001

Now we’re ready to configure your new payment method. Click the newly created node and select “Eway” in the Service drop down list and select “Checkout” in the pipeline drop down list. Remember to fill out the rest of the required information in the rest of the Tabs.

When you’re done, click the save icon. That’s everything in the uCommerce interface.

clip_image003

Please not that eWAY only supports Australian dollars (“AUD”).

clip_image005

if AUD does not appear under the pricing tab follow the next step ”Setting up Australian dollars at currencies” to add Australian dollars under currencies. Otherwise click the save icon and you’re done.

Setting up Australian Dollars at Currencies

clip_image007

Right click the currencies leaf and click create. The ISO code for Australian dollars is “AUD”. When you’re done, click the save icon. That’s everything in the uCommerce interface. Proceed to “2.0 Editing the EWay.config file”

Editing the EWay.config file

Now we need to edit the EWay.config file in order to match your environment.

You’ll find the config file at “rootdir\umbraco\UCommerce\Configuration\EWay.config” where rootdir is the location on your computer, where umbraco is installed.

image

customerId: must be found at your sandbox environment at the bottom of the page after you have logged in using your account credentials :

clip_image010

username: corresponds to your eWAY account username

debug: no need to configure

callbackUrl: no need to configure

cancelUrl: this is the page the customer would be redirected to after a cancellation at the secure payment page at eway.

acceptUrl: this is the page the customer would be redirected to after a successful payment at the secure payment page at eway.

Both the cancelUrl and acceptUrl is a local web in your website such as “orderconfirmation.aspx”

Now everything is configured to your webpage and should work as intended.

posted on Monday, February 13, 2012 4:30:30 PM (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback

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

With Braintree you are responsible for hosting the payment form. A simple form is provided by uCommerce, but it will need a better look and feel. Acquire, cancel, and refund are available. This is implemented with the Transparent Redirect method.

A wide range of currencies available, but you decide which currency to use when you create a merchant account. Each merchant account can only process a single currency.

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

clip_image002

Click the newly created node and select “Braintree” 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_image003

That’s everything in the uCommerce interface.

Optional Settings in Braintree gateway

All those settings in the Braintree gateway are optional.

You log into your account at https://www.braintreegateway.com/login and sandbox at

Configure Validation Rules

On the Menu at the top, click “Processing” and the click “Add/Edit” in the CVV line.

clip_image005

Make sure that all is checked, and “For Any Transaction” is selected, to get CVV validation enabled. End by clicking “Save”.

clip_image007

Editing the Braintree.config File

Now we need to edit the Braintree.config file.

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

clip_image009

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

Finding merchantId

On the Menu at the top, click “Account” -> “My User” –> “API Keys”.

clip_image011

Here you find “merchantId”:

clip_image012

Finding publicKey

In the Menu at the top, click “Account” -> “My User” –> “API Keys”. Here you find the “publicKey”.

clip_image013

Finding privateKey

On the Menu at the top, click “Account” -> “My User” –> “API Keys” -> “View”. Here you find the “privateKey”.

clip_image014

Finding callbackUrl

Unless you have implemented your own version of the callback handling, this should be set to “(auto)”.

Finding paymentFormUrl

You can optionally host the payment form inside your own pages. To do this override the value “(auto)” with the URL on which the payment form is rendered.

Remember to use the CommerceLibrary:RenderPaymentForm or the RenderPage of the IPaymentWindow. Please find code samples in a later section.

Finding paymentFormTemplate

Path to the paymentFormTemplate. The default paymentFormTemplate BraintreePaymentForm.htm is located in the Configuration folder under uCommerce.

Finding acceptUrl and declineUrl

To get the customer redirected back to you page after ended payment, you have to specify a return url depending on payments result: Accept or decline.

Finding debug

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

Finding testMode

Test mode will toggle the payment method service to use a test environment. A sandbox account is used in testMode.

Valid values “true” or “false”.

Excecuting 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, open Umbraco click “Commerce” select the payment method (“Braintree”). In the pipeline drop down list select Checkout and then click “Save”.

clip_image016

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.

Set Look and Feel on the Payment Form

The payment form is populated with the contents of paymentFormTemplate file chosen in the config file, no matter which way you choose to integrate it.

The HTML inputs that have a name specified in the default file are needed to submit the form to Braintree. It is possible to changes types of the fields, add other attributes and move the fields around, but they must retain the names assigned to them.

The Braintree provider will insert values at runtime by replacing placeholder values, e.g. “##XX##” tags. You can safely remove these placeholders if you wish to handle the form values yourself.

Integrate the Payment Form into Your Own Page

If you want to integrate the payment form into one of your pages you’ll want to modify the template HTML to include only the form element and get rid of the html and body tags.

Integrate the form using Razor

Sample code:

@using UCommerce.EntitiesV2;
@using UCommerce.Transactions.Payments;
 
@{
 
    var paymentGuid = HttpContext.Current.Request["paymentGuid"];
    
    var payment = Payment.All().Single(x => x.PaymentProperties.Where(y => y.Key == "paymentGuid" && y.Value == paymentGuid).Count() > 0);
    
    var paymentMethod = payment.PaymentMethod;
    
    var paymentWindow = paymentMethod.GetPaymentMethodService() as IPaymentWindow;
 
}
 
@Html.Raw(paymentWindow.RenderPage(new PaymentRequest(payment.PurchaseOrder, payment)))

Integrate the form using XSLT

Sample code:

<xsl:variable name="paymentGuid" select="umbraco.library:RequestQueryString('paymentGuid')"/>
<xsl:value-of select="CommerceLibrary:RenderPaymentForm($paymentGuid)" disable-output-escaping="yes"/>

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_image018

ToCompletedOrder.config

clip_image020

FAQ

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

posted on Monday, February 13, 2012 4:23:41 PM (Romance Standard Time, UTC+01:00)  #    Comments [0] Trackback

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

With the Authorize.Net you can do authorization of payments, acquire payments and cancellation of payments both via uCommerce and the back end office of your Authorize.Net subscription.

Settings in uCommerce

Add a new payment method, under “uCommerce => Settings => Orders => Payment Methods”, by right clicking the “Payment Methods” leaf and use “Create”. You can use any name you like; I have used “Authorizedotnet”.

image

Now we’re ready to configure your new payment method. Click the newly created node and select “Authorizedotnet” in the Service drop down list and select “Checkout” in the pipeline drop down list. Remember to fill out the rest of the required information in the rest of the Tabs.

When you’re done, click the save icon. That’s everything in the uCommerce interface.

image

Settings in Your Back-end Office at Authorize.NET

You log in using the “Merchant Log In” page.

First you need to log in to your back end office at: http://Authorize.net

We need to configure your MD5-Hash used for secure communication between your server and Authorize.NET. Click MD5-Hash and create and submit. You need to have this ready by your hand in one of the following steps.

image

Next we need to configure the payment form.

image

Click “Form fields” in the page you enter after clicking “Payment Form” on the page above.

Check the following boxes off:

image

Now we need to visit “API Login ID and Transaction key” section.

image

Now you need to create a Transaction Key by answering your secret question which you created upon creating your Authorize.NET account.

Make sure you have the “API Login ID” and “Transaction Key” by your hand as you need them in the last step on configuring your configuration file.

image

Configuring Auto Acquire and Cancel Payments

Authorize.Net comes with the ability to do automatic acquire and cancel payments. In order to make this work you need to enable a pipeline task.

To enable auto acquire edit the “ToCompletedOrder” pipeline.

To enable auto void/refund edit the “ToCancelled” pipeline.

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

image

Simply remove “<!-- “ and “-->” at the highlighted line. These are HTML comment sections.

Configuring the “Authorizedotnet.config” File

Now we need to edit the ”Authorizedotnet” file in order to match your environment.

You’ll find the configuration file at “rootdir\umbraco\UCommerce\Configuration\authorizedotnet.config” where rootdir is the location on your computer, where Umbraco is installed.

Parameter list for the configuration file:

Parameter name

Value

apiLogin

The API login ID from the backend. Please refer to section of settings in Authorize.NET backend

TransactionKey

The transaction key you’ve created in the back-end configuration.

Md5Hash

You’ll have to define this hash key yourself. Please refer to section of settings in Authorize.NET backend

acceptUrl

This URL redirects your customer back to a specific page at your site after a successful authorization.

declineUrl

This URL redirects your customer back to a specific page at your site if an authorization is declined.

payType

Tells our system what command to send to Authorize.NET

testMode

Application is in test mode. This must be set to false.

debug

Application is in debug mode or not. Set to false for live environments

instantAcquire

Perform instant capture on payment or authorization of a payment.

sandboxMode

Set to true for the sandbox environment and false for test/live environments.

 

image

Congratulation - your website now includes payments with the Authorize.NET.

Important: When authorization has been succesfully completed, Authorize will redirect the customer to the acceptpage but notice this page will be under the Authorize.Net’s URL. This is not an error.

posted on Monday, February 13, 2012 4:15:48 PM (Romance Standard Time, UTC+01:00)  #    Comments [1] Trackback

uCommerce comes with built-in support for Amazon FPS payments. This guide will help you to setup your installation to use Amazon FPS as payment.

Settings in uCommerce

To add a new payment method to uCommerce, go to the Commerce section in your Umbraco installation.

clip_image002

Navigate to “uCommerce => Settings => Orders => Payment Methods”. Right click on the node “Payment Methods” and click “Create”.

clip_image004

A box will appear. Here you can enter any name you like but it’s recommended to use “Amazon FPS” so you easily can find it again.

Now we have to configure the payment method. Click on the node with the name you have chosen. In the service dropdown list you choose “Amazon FPS” and select “Checkout” in the Pipeline dropdown list. Remember to give the service a “Display name” which you find in your language tab in the same window.

clip_image006

Amazon FPS does only support US Dollars at this point, so if USD doesn’t appear under the “Pricing” tab you have to follow the next step “Setting up US Dollars at currencies”. Otherwise click the save icon and skip the next step.

clip_image008

Setting up US Dollars in Currencies

clip_image010

Right click the currencies leaf and click create. The ISO code for Australian dollars is “USD”. When you’re done, click the save icon.

Signing up for a Amazon FPS account

To use the Amazon FPS with uCommerce you have to register first. Go to https://payments.amazon.com and go to the “Developer” tab in the top menu. Under the “Developer” tab click “Sign Up For Amazon FPS”. Create a new account or use an existing account if you already got one you wish to use.

clip_image011

Follow the instructions on the screen to complete the registration. When the registration is complete you receive a confirmation to the e-mail address you used for the registration.

Setting up the Amazon FPS config file

Now we need to edit the Amazon.config file in order to match your environment. You will find the config file at “(root dir)\umbraco\UCommerce\Configuration\Amazon.config” where “root dir” is the location on your computer where umbraco is installed.

clip_image013

debug: Not used by this provider.

testMode: Indicates whether the Amazon FPS is using the Sandbox or production environment. If you want to test your payment service this setting MUST be set to “True” otherwise the Amazon FPS will be in production environment and will charge a customer.

debug=”True” – For sandbox environment

debug=”False” – For production environment

awsAccessKey: This key is used to identify the account. You can find this key here: http://aws.amazon.com/security-credentials. If you’re not logged in you will be asked to do so.

awsSecretKey: This key is used to create your signature and it’s important to keep this secret from people who is not in need of this. You can also find this key at the security credentials at amazon. Use the same link above.

acceptUrl: This is the page the customer will be redirected to after a payment has been authorized at Amazon. In the picture above there is an example how it can look like.

cancelUrl: This is the page the customer will be redirected to if the customers abandons payment at Amazon.

callbackUrl: this need to be configured. You need to know what id the payment method has in the database. Look at the next step to see how to find this id. The URL should be on the form of: http://(domain name)/(id)/PaymentProcessor.axd

How to find your payment method id in your database

To find your payment method id you need to make a query. One way to make this query is using SQL Mangement Studio. Connect to your SQL server. In SQL Management click “New Query” in the tools menu right under the file menu. Choose the database where you have your umbraco/uCommerce installed.

clip_image014

In the text editor in write the following:

SELECT * FROM ucommerce_paymentmethod WHERE Name = 'Amazon FPS'

The text between ‘’ is the name of the service you choose in step 1.1. Then press “F5” on your keyboard to execute the query. In the bottom of the text editor window a result window should appear.

clip_image015

The number which is in the column “PaymentMethodId” is the number you need in your Amazon.config file.

Setting up the Instant Payment Notification messages in Amazon FPS.

Amazon FPS sends notifications when a status on a transaction changes. That can be when a transation is changing from “Pending” to “Success”. To setup this you need to go to your account management. Navigate to https://payments.amazon.com in your browser. Click on “Your Account” tab and type in your login credentials.

In your control panel go to “Edit My Account Settings à Manage Developer and Seller Preferences”. In the textbox right for “URL for Instant Payment Notification” type in the url in the following format: http://(domain name)/(paymentmethodId)/PaymentProcessor.axd

clip_image017

Note: The URL you type in this field has to match the callbackUrl in the Amazon.config file or Amazons signature will be rejected and payments will not be available.

Configuring Auto Acquire and Cancel Payments

The Amazon FPS  provider comes with the ability to do automatic acquire and cancel payments. In order to make this work you need to enable a pipeline task.

To enable auto acquire edit the “ToCompletedOrder” pipeline.

To enable auto void/refund edit the “ToCancelled” pipeline.

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

clip_image018

Simply remove “<!-- “ and “-->” at the highlighted line. These are HTML comment sections.

posted on Monday, February 13, 2012 4:08:55 PM (Romance Standard Time, UTC+01:00)  #    Comments [1] Trackback
«Older Posts