Integrating A Tax Provider

From AbleCommerce Wiki

Sample Provider

To integrate a tax provider with Ablecommerce 7 you must implement CommerceBuilder.Taxes.Providers.ITaxProvider interface. This interface defines how tax providers interact with Ablecommerce. This should be done by extending the TaxProviderBase class. Below is a sample code to get you started. All you need to do is create a new windows class library solution, paste this code into a new class, and set a reference to the CommerceBuilder.DLL file. Once you have the solution set up, you must implement the properties and methods for your specific provider.

using System;
using System.Collections.Generic;
using System.Text;
using CommerceBuilder.Common;
using CommerceBuilder.Orders;
using CommerceBuilder.Taxes.Providers;
 
namespace SampleTaxProvider
{
    public class TaxProvider : TaxProviderBase
    {
        #region Properties
        /// <summary>
        /// The name of the tax provider implementation
        /// </summary>
        public override string Name
        {
            get { throw new Exception("The method or operation is not implemented."); }
        }
 
        /// <summary>
        /// The version of the tax provider implementation
        /// </summary>
        public override string Version
        {
            get { throw new Exception("The method or operation is not implemented."); }
        }
 
        /// <summary>
        /// Is the tax provider activated or not
        /// </summary>
        public override bool Activated
        {
            get { throw new Exception("The method or operation is not implemented."); }
        }
        #endregion
 
        /// <summary>
        /// Initialize the tax provider with the given configuration data. Called by AC at the time of initialization.
        /// </summary>
        /// <param name="taxGatewayId">The tax gateway id</param>
        /// <param name="configurationData">Configuration data in the form of name value paris</param>
        public override void Initialize(int taxGatewayId, Dictionary<string, string> configurationData)
        {
            base.Initialize(taxGatewayId, configurationData);
        }
 
        /// <summary>
        /// Calculate the taxes using this provider for the given basket
        /// </summary>
        /// <param name="basket">The basket to calculate tax for</param>
        /// <returns>Total tax calculated</returns>
        public override LSDecimal Calculate(Basket basket)
        {
            throw new Exception("The method or operation is not implemented.");
        }
 
        /// <summary>
        /// Cancel the taxes by this provider for the given basket
        /// </summary>
        /// <param name="basket">The basket for which to cancel the taxes</param>
        public override void Cancel(Basket basket)
        {
            throw new Exception("The method or operation is not implemented.");
        }
 
        /// <summary>
        /// Commit the taxes by this provider for the given order
        /// </summary>
        /// <param name="order">The order for which to commit the taxes</param>
        public override void Commit(Order order)
        {
            throw new Exception("The method or operation is not implemented.");
        }
    }
}

Method Overview

When you extend TaxProviderBase class you need to implement the abstract methods and properties defined in this class. Some of the properties and methods are for information purposes only and are easy to implement. For example Name and Version.

The important methods to implement are Calculate, Commit and Cancel.

Calculate

This method takes a basket object as input. From there, you can get the billing and shipping addresses as well as line items. What you need to do is determine the tax to charge - then add line items to the basket (BasketItem class) for each line item. The method returns the total tax that was added to the basket.

Commit

This method takes an order object as input and commits any taxes that were charged. This may not be required by your integration. Some providers may need to know what taxes were actually charged in order to produce accurate reports on tax liability.

Cancel

This method takes a basket object as input. When called, it cancels any tax charges currently in progress. Your integration may or may not require this. Some providers may use this to reset the calculations for a particular order in progress.

Deployment

7.0.3 and higher

Once your class is compiled, place it into the bin folder of the AbleCommerce installation. Then log into the merchant admin and go to Configure -> Taxes -> Third Party Providers. If your provider is properly installed, it should show on this screen with an option to activate it for your store.

7.0.2 and lower

In these versions, there is no graphic interface for registering a third party tax provider. In order to connect your provider you must add a record to the database in the ac_TaxGateways table:
TaxGatewayId = auto number ID
StoreId = ID of your store, probably 1
Name = Name of your gateway
ClassId = .NET Class ID used to create an instance of your gateway. The class ID should follow the format of class name, assembly. For example: MyNamespace.SampleProvider, SampleProvider.dll.
ConfigData = If you need to provide configuration data it can be stored here in a url encoded string. For example, key1=value&key2=value. The values in the field will be accessible in your integration by using the GetConfigData() method. If you are producing an integration that will not be distributed to others, it would be simpler to hardcode any needed configuration in your provider implementation.

Resources

• Community Forums Discussion