Integrating A Tax Provider
Contents
ITaxProvider
To integrate a tax provider with Ablecommerce 7 you need to implement CommerceBuilder.Taxes.Providers.ITaxProvider interface. This interface defines how tax providers interact with Ablecommerce.
In version 7.0 final, ITaxProvider interface is defined as follows
/// <summary>
/// Interface that must be implemented by tax providers
/// </summary>
public interface ITaxProvider
{
/// <summary>
/// The gateway Id of the tax provider. This is passed at the time of initialization.
/// </summary>
int TaxGatewayId { get; }
/// <summary>
/// The name of the tax provider implementation
/// </summary>
string Name { get; }
/// <summary>
/// The version of the tax provider implementation
/// </summary>
string Version { get; }
/// <summary>
/// Is the tax provider activated or not
/// </summary>
bool Activated { get; }
/// <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>
void Initialize(int taxGatewayId, Dictionary<String, String> configurationData);
/// <summary>
/// Get the configuration data in the form on name value pairs
/// </summary>
/// <returns>The configuration data as name value pairs</returns>
Dictionary<string, string> GetConfigData();
/// <summary>
/// Cancel the taxes by this provider for the given basket
/// </summary>
/// <param name="basket">The basket for which to cancel the taxes</param>
void Cancel(Basket basket);
/// <summary>
/// Commit the taxes by this provider for the given order
/// </summary>
/// <param name="order">The order for which to commit the taxes</param>
void Commit(Order order);
/// <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>
LSDecimal Calculate(Basket basket);
}
TaxProviderBase
To implement a tax provider you can either implement the ITaxProvider interface directly or you can extend the CommerceBuilder.Taxes.Providers.TaxProviderBase class. For the sake of easy upgrades in future it is highly recommended that you extend TaxProviderBase class instead of directly implementing the ITaxProvider interface.
The TaxProviderBase class is defined as follows
/// <summary>
/// Base class for tax provider implementations
/// </summary>
public abstract class TaxProviderBase : ITaxProvider
{
private int _TaxGatewayId;
/// <summary>
/// The gateway Id of the tax provider. This is passed at the time of initialization.
/// </summary>
public int TaxGatewayId
{
get { return _TaxGatewayId; }
set { _TaxGatewayId = value; }
}
/// <summary>
/// The name of the tax provider implementation
/// </summary>
public abstract string Name { get; }
/// <summary>
/// The version of the tax provider implementation
/// </summary>
public abstract string Version { get; }
/// <summary>
/// Is the tax provider activated or not
/// </summary>
public abstract bool Activated { get;}
/// <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 virtual void Initialize(int taxGatewayId, Dictionary<string, string> configurationData)
{
this._TaxGatewayId = taxGatewayId;
}
/// <summary>
/// Get the configuration data in the form on name value pairs
/// </summary>
/// <returns>The configuration data as name value pairs</returns>
public virtual Dictionary<string, string> GetConfigData()
{
Dictionary<string, string> configData = new Dictionary<string, string>();
return configData;
}
/// <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 abstract void Cancel(Basket basket);
/// <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 abstract void Commit(Order order);
/// <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 abstract LSDecimal Calculate(Basket basket);
}
Implementing Required Methods
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
Once your class is implemented and compiled, you need to register it with the store. Since we did not include our tax providers, there is no web based interface to do this yet. The simplest choice, if available, is to 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. For examples, you can look in ac_PaymentGateways (assuming you have a gateway configured).
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 only for yourselves, you don't need to worry about this as any configuration should be hard coded instead.
Resources
- Complete Source of implementation of CCH Tax Gateway ... TODO
- Community Forums Discussion
