Tax Provider Extension Point

Overview

We make it our mission to provide the most flexible e-commerce platform possible that allows you to fit the needs of nearly any e-commerce use case.  This is why we made sure that you have a way to implement your own or third-party tax calculation providers.  This article will help you implement any custom tax provider using the sample Visual Studio solution.  It's nearly the same as implementing a custom payment gateway for credit cards.

Requirements

The following is required to accomplish the goals of this article:

• How to use Visual Studio 2012 or newer
• Familiarity with C# and Razor
• General understanding of frameworks
• Have a site with Hotcakes Commerce 1.10.0 or newer installed and ready

Getting Started

Download Sample Tax Provider Project

You are about to use a Visual Studio project to connect to your Hotcakes Commerce store.  The project can be downloaded on the right.  The documentation below will walk you through how to use this project.

Make sure you have a development website ready to develop against.  This would consist of the DNN CMS with Hotcakes Commerce installed and configured. Also, if you do not already have products in your store, you should consider adding some or adding the sample products.  This could even be a locally restored back-up of your production website.

Tax Provider Sample Solution

If you haven’t done so already, make sure your site is up and running and ready for your project to call into it.

We are about to have you set up your project.  Once you understand how this works, feel free to set up your project and solution in any way that works for you.  Also, please do not do this development work on your production website.

Open the download from above using your favorite zip utility.  Grab all of the files from the zip archive and unzip them into the root of your development site.

If you receive any prompts from Windows, it’s likely that you already have a set of Hotcakes project files added to your development site.  Go ahead and overwrite the files.  This should result in MyTaxProvider, References, and MyTaxProvider.sln folders and files in your site folder like shown below.

Next, open the solution that is now in the root of your website.  Double-clicking on it will do the trick.  This will open Visual Studio and show your project open.  Your Solution Explorer view should look similar to the image below.  Please note that you probably want to make sure that Visual Studio is open in "Administrator" mode before beginning to code though.

From this point, you are ready to begin writing the code necessary to create your new payment method.  This will primarily consist of the settings and API code required by your tax provider of choice.  Your chosen tax provider should have documentation and/or code samples to help with this.

Solution Files

You have a few files available for you to modify and they will all be necessary to work with for your new tax provider.  The table below will walk you through what each file is for.

File Name	Description
Edit.ascx.resx	This is what's known as a localization file.  Keeping this file updated will ensure that your provider runs equally well in whatever language that the merchant happens to be editing the store in.  If you want to add a translation for another language, simply include the appropriate language code for that language in the file name.  As an example, if you wanted to support French, the file name might be Edit.ascx.fr-FR.resx instead.  You should otherwise not change the name of this file.
Edit.ascx, Edit.ascx.cs	This file will be injected into the Hotcakes store administration to allow you to display and save settings input by the merchant.  This is a common way to save API credentials, endpoints, and anything else that you need.  You should not change the name of this file.
MessageBox.ascx, MessageBox.ascx.cs	This is a user control that you can optionally choose to use to display various status messages within your Edit control.  It abstracts the message in a way that allows for you to choose to apply different styling, business rules, and more.
MyTaxProvider.cs	This class file is where the result of the tax communication is primarily handled.  This is an abstraction to allow your code to focus on the core operation, outside of the business logic.
MyTaxProviderGateway.cs	The gateway class allows you to run your business logic, based upon what may have happened in the MyTaxProvider class.  This is similar to the steps that a payment gateway might behave, such as using actions like cancel, commit, and get taxes.  You must change the GUID's that are in the current class file to ensure that you don't conflict with any other providers.
MyTaxProviderLineResult.cs	When you receive taxes back from your respective tax provider, each line item in your order should have a result object, defined within this class.  It is both used to post back to and commit taxes to your provider as necessary and to update your order with the relevant details.  You should fill the properties in this object as completely as possible to avoid any unanticipated issues with orders and accounting.
MyTaxProviderResult.cs	The tax provider gateway uses this result object fairly extensively in most implementations.  This object will contain all of the results from your tax provider, including the line item results, and be used to update the order details as appropriate.  You should fill the properties in this object as completely as possible to avoid any unanticipated issues with orders and accounting.
MyTaxProviderSettings.cs	The settings class provides you with a way to get and set settings for your provider easily, and in a fully qualified way.  This class is primarily used in the Edit.ascx.cs file, but also may be referenced in other classes as required.

Steps to Build/Code

If you've made it this far, you're already well on your way.  Now, you just need to add and modify the code in the solution as discussed in the table above.  This may also include changing namespaces, DLL names, class/file names, and more.  You'll want to test these changes like with any other code you might write to ensure that everything works as expected.

If you do change the class names, you should be sure that they continue to match a common naming convention, and that convention should match the parent folder name.  As an example, if your company name is Acme, you might change MyTaxProvider everywhere to AcmeTaxProvider.  Again, this would include the parent folder name.  In the case of MyTaxProviderResult, that would become AcmeTaxProviderResult.  Continue to use the same naming convention throughout your project.

When you're at a point to see what your changes look like, you need to follow the deploy steps below.

Deploying Your Code

There are different steps to deploying your code, depending on whether you're just developing or attempting to roll it out to a server (e.g., staging or production).

• Development
• Production

Deploying Your Code – Development Environment

If you are in your development environment, all you would need to do is:

1. Ensure that you are building to the /Bin directory of your website (debug mode)
2. Copy the Edit.ascx, MessageBox.ascx, and resx files to the same path in your site:  ~/DesktopModules/Hotcakes/Admin/Parts/TaxProviders/YOURPROVIDERNAME/
3. Go to the store administration and change the tax provider to use the new custom order workflow in this project in the Settings > Gift Card Settings view

Once you copy the DLL and project files, you will be able to select the new tax provider in your Store Admin > Settings > Taxes view.

You'll now see your newly created tax provider shown in the drop-down list.  If you select it, you can then edit the settings you added.

Here, you can see the settings from the custom project, as you defined them.  Don't forget to save them here and in the previous view.

Deploying Your Code – Production Environment

Once you are happy with the results of your payment gateway, build it in release mode and copy the DLL you have built to the /Bin directory of your production website.  The name of the DLL will be whatever you have chosen to name it in your project properties.

You would also copy the same files we moved during development into the same paths in your production environment.  If this is your first time deploying the tax provider, you’ll need to create the respective folders as well.

That’s it… We hope you think that this is as easy as we do!