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

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.

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 :)

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

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

Tim Gaunt, The Site Doctor, UK

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 popped up in the community in 2011 with his company byte5 immediately producing high quality stores with uCommerce.

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.

uCommerce 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:

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.

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.

A Bit Of Background

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

A campaign to group marketing activities aka campaign items

A campaign item to aggregate targets and awards

One or more targets to determine when the campaign item is displayed to the customer, e.g. Customer is looking at the Clothing category

One or more targets to determine when an award is triggered, e.g. Buy for more than 400€

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

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 :)

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

A 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:

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.

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:

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.

What Makes An "Outbound User Post"

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:

Payment details such as currency, amount, etc. are sent to the gateway

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

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

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

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

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

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.

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

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

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

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

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

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

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.

Settings in Your Back-end Office at Ogone

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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

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

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.

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

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.

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

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.

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.

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

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

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

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.

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:

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.

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

Finding subId

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.

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

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.

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

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.

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.

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.

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

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.

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

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

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.

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

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.

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.

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

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

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.

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

Finding paymentFormTemplate

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

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.

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

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.

Settings in Your Back-end Office at 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.

Next we need to configure the payment form.

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

Check the following boxes off:

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

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.

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.

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.

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.

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.

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.

Setting up US Dollars in Currencies

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.

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.

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.

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.

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.

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

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.

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