Overview

It’s easy to use TaxCloud with Simplify Commerce to automatically calculate and collect sales tax for any street address in the United States. We are proud to announce the immediate availability of taxcloudSimplify.js, a new version of our TaxCloud javascript library that has been designed specifically for merchants using Simplify Commerce.

Steps 1, 2, 3, and 4 (indicated in orange) are the normal Simplify process, and are not altered by our efforts here today. Rather, the steps we will be adding (indicated in blue) will allow TaxCloud to manage sales tax – these steps happen immediately before, and immediately after the Simplify steps. In sequence, the revised order is as follows:

A. Tell TaxCloud about all the items being purchased (by category), including where they are being shipped from, and where they are going.

B. TaxCloud will respond with the amount of sales tax to collect.

[then you begin the normal Simplify Process]

1. At the checkout, you will display a form (which taxcloudSimplify.js provides in our example today) that collects required payment information. Simplify’s JavaScript library (Simplify.js) encrypts the data and sends it to Simplify Commerce servers.

2. The Simplify Commerce server will return a single-use token that represents the payment information.

simplify.js – a library provided by Simplify to handle purchases with a credit card

jquery.min.js – everyone knows about JQuery, right?

HelloSimplify.html – a sample page using everything described in this post

As I mentioned earlier we will be using the built-in UI cart that taxcloudSimplify.js supports. The goal of this is to make things as easy as possible for web masters to show a cart of items with their tax as a line item, provide a simple credit card collection page and printable receipt. Our sample using this solution covers everything described in this post is a little over 50 lines in length and works. Download the HelloSimplify.html page and take a look at it. If you put HelloSimplify.html on your web server you can step through all the concepts described here at your convenience. Don’t worry, when you start with TaxCloud your account is in test mode. It doesn’t become live until you say so!

Act 1: The Setup

First thing we need to set up is the proxy page/script that will run on your web server. We have two flavors for you to choose from:

If you are using another server processing extension you can either create the same page functionality on your platform (nothing tricky going on) or let us know so that we can create it.

Open TaxCloud.php/TaxCloud.aspx in your editor and take a look at it. This file has two purposes:

It holds your credentials for TaxCloud

It receives posts from our taxcloudSimplify.js library running in your domain and forwards the data to our TaxCloud web service running in our TaxCloud.net domain.

While you have TaxCloud.php/TaxCloud.aspx open, lets go ahead and add your unique credentials.

The credentials you need are from your TaxCloud account, specifically your apiLoginID and apiKey. Log into TaxCloud and go to the Websites Section. Select your website, and your ‘API ID’ and ‘API KEY’ will be displayed.

Note that we are including with ‘https’ because we are doing a purchase page. Payment processors usually have this requirement. In fact, as we are demonstrating integration with Simplify, we need to ensure https per their requirements:

Of course, if your site already uses a JQuery UI Theme, you can omit this link, and the taxcloudSimplify.js UI will look like the rest of your site automatically.

Now we will look at the actual javascript code needed to make all this work. This seems like a good spot to introduce the TaxCloud objects defined in taxcloudSimplify.js. They are:

TaxCloudConnection — this handles the actual network communication between the web page and TaxCloud (via TaxCloud.php/TaxCloud.aspx).

TaxCloudAddress — this class makes it easy to use a shipping address with both the US Post Office (for verification) and TaxCloud (for tax lookups)

TaxCloudCartItem — represents an item in your cart a customer can purchase. It has a price, quantity and Taxability Information Code (TIC). [You will need to be logged-in to review complete TIC documentation]

Next we have to set the Simplify public key for TaxCloud to use. Not much will happen without this. Go to your Simplify dashboard to get your public key.

You can also see that we have set the TaxCloud variable “storeName” – you should set this to the name of your store, which will be seen by your customers in the checkout UI titlebars.

After initializing TaxCloud, we use JQuery’s ready() to register an event and finish “installing” taxcloud on your HTML page.
TaxCloud has several events you can hook into during the processing of the address and cart. Every button you see in the TaxCloud UI can be wired for a callback in case you need to do any special processing. For example, this can notify you that the customer has completed the cart steps (provided their shipping address and looked up their tax information) and therefore a ‘Grand Total’ is available. You could stop the default TaxCloud processing, grab that grand total and begin your own unique purchase process. Or you can let TaxCloud handle everything. The choice is yours.

The last line in this code snippet sets the unique customer id for the end user. The customerID is a field you supply that uniquely represents the customer. The function also takes a flag that tells TaxCloud whether or not to retrieve previous address and cart information, if found. This handles the case where people start a purchase, cancel it and then return later to pick up where they left off. Right now we only store this information for 24 hours. You can use this customerID later to view customer specific transactions in our activity log. The customerID field is required.

Fabulous, taxcloudSimplify.js is now installed and ready to go to work.

Act 3: Where are you?

We have one more step before you can get onto the business of selling things. You need to tell taxcloudSimplify.js what your address is (your store or office location). Note: This location must also be added to the TaxCloud website, in the Locations section.

Act 4: The Products

Next we need to let TaxCloud know what the items are that we will be checking tax information for. This means we need to create a TaxCloudCart with a list of TaxCloudCartItem objects. Each TaxCloudCartItem object has five properties:

an item identifier (a SKU works great) but we do not recommend using a title or product name – this identifier is for machine use, not human use

the item display name or brief description – this one is for human use

the unit price

a quantity

a TIC (remember that Taxability Information Code?)

You can add TaxCloudCartItems to the TaxCloudCart one at a time or in bulk. For example, to add a single item at a time you could create a button as follows:

The ‘onclick’ handler adds the new TaxCloudCartItem to the TaxCloudCart, which triggers an internal event so that it immediately appears in the UI. Then the ‘onclick’ handler does a Lookup to update all the line items in the cart, including the new one we just added.

Act 5: The Customer

Once we have the origin address and the cart in place we need to get the shipping address, verify it and do the tax lookup. Here we will make use of the taxcloudSimplify.js built-in UI to display an address form the customer can fill out. We respond to a click event on the page to start the purchase flow. In this case we created a standard button that a JQuery handler will catch the ‘click’ event for. I named it with id=’TaxCloudPurchaseButton’, but you can call it anything you like.

When a user clicks the button identified by ‘TaxCloudPurchaseButton’, it fires the javascript code above and taxcloudSimplify.js initiates the UI.

Specifically, it calls ‘Open()’. This tells the TaxCloud library to use its built-in UI components. Once this call is made the UI pops up to obtain the customer’s shipping address.

This form will be filled out by the customer and represents their shipping address for all the items in the cart. If the customer is outside of the USA they can click the ‘My shipping address is not in the USA’ checkbox and TaxCloud will not compute sales tax for the items in the cart. The button at the lower-left lets them know the ‘state’ of their address. That is, if its verified or unverified. At this point, you can click on the USPS verify address button if you want the US Post Office to validate what you have entered, but it is not necessary because taxcloudSimplify.js does this automatically when you press ‘Next’. So, let’s enter an example shipping address to work with and click ‘Next’ to go to our second page.

Now we see all the items in our cart. Lets talk for a moment about what else is going on here. You can see now that the address has been verified (or verification failed). You don’t need to have a verified address in order to complete a purchase, but a verified address will ensure the most accurate sales tax rates.

After attempting to verify the address, taxcloudSimplify.js proceeds to lookup the correct sales tax amount due for each item in the cart. These calls happen asynchronously, which means the customer may see the sales tax amounts appear/update in the cart.

We also see each item listed with a unit price, the current quantity, the line item price, the line item tax amount and the line item total (price + tax). Finally, just above the ‘Update’ and ‘Purchase’ buttons we have the total, which is the sum of price and tax for all line items.

This form is interactive as well in that the customer can change quantity amounts and everything will be looked-up and computed again. Simply adjust a quantity and either click in another field to trigger the update, or click the ‘Update’ button. The new prices and tax amounts will be changed in the screen when the asynchronous calls receive their responses.

At this point you may be curious what code you need to add in order to handle the transition from the first purchase page to the second. The answer is no additional code is needed. The TaxCloud library, being UI aware, handles this transition for you. We do make callback hooks available if you require additional processing before proceeding, but we’re keeping things simple for the time being. In a future post we will look at all the TaxCloud UI events available.

Act 6: The Purchase

Once the customer agrees with their cart they click ‘Next’ to purchase the items in the cart. This brings up the third tab containing a very simple credit card form modeled right from Simplify. All of the best practices recommended by MasterCard Simplify Commerce are followed on this page for your, and your customers, peace of mind.

The purchase amount is carried forward from the items tab and the rest of the fields the customer fills in. Once that is done they click ‘Process Payment’. Again, taxcloudSimply.js will handle the payment processing by default. You can attach a callback so that you handle your own payment process if you like.

So what does the Simplify purchasing code look like? Our implementation looks like this:

This is a fair amount of code that you don’t have to do yourself. But, again, the choice is yours as you notice a conditional user supplied callback that lets you gain control of the actual payment processing:

if (this.OnPurchaseStep3ProcessClicked)
this.OnPurchaseStep3ProcessClicked(this);

To enable this callback simply set the TaxCloud.OnPurchaseStep3ProcessClicked value to a function and it will be called at the appropriate time.

One additional step that TaxCloud handles for you is the ‘Capture’ notification to TaxCloud that lets the system know funds will be transferring and sales tax should be retrieved. If you handle the ‘OnPurchaseStep3ProcessClicked’ event, then you will also need to handle the ‘AuthorizedWithCapture’ call to TaxCloud’s servers.

Act 7: The Receipt

Even though everything has been handled online, a receipt is still valuable for helping the customer feel secure in their purchase. Upon a successful purchase, TaxCloudSimply lists out details of the sale onto a printable page.

At this point we are done. The items have been identified, the sales tax was calculated, the grand total was used to process a payment and TaxCloud was notified of the event for future tax collection. So what was the sum total of javascript that a web developer had to write in order to make all this happen? Given an HTML purchase page, they could start by copying and pasting the following into a javascript block:

This is our second iteration of TaxCloud javascript integration and we are excited to hear your feedback as to how to improve it. Our goal is to make calculating sales tax as easy as possible for everyone – at no cost.

One last thing

Congratulations are in order! You have successfully integrated real-time sales tax for your customers – and you probably did it in less than an hour. Now that you have completed a transaction with your account in test-mode, you should return to TaxCloud, go to the Websites section, and click Go Live. This is important so that TaxCloud can begin preparing your monthly sales tax reports – and in 24 states, TaxCloud can even file your returns and remit your sales tax proceeds for you (with more states coming soon).

We have a new library for anyone who needs to calculate sales tax and prefers to work with Javascript on the client side. We call it ‘TaxCloud.js’ and you can use it purely as a library of TaxCloud-specific API calls, or as a very simple UI shopping cart to collect items and determine sales tax due (based upon your customer’s address) before you send a total purchase amount to your purchasing platform.

In this post we describe how to use our simple UI cart option. Then we will show you how to send the total purchase amount (with sales tax) to your payment processor. In our example, we will be using Stripe, but these bits will work just as well with other payment services, such as PayPal, Google Wallet, Braintree, etc. With this scenario you can add TaxCloud.js to your order processing as a step before your payment system. Let’s take a look.

The basic process when a customer wishes to purchase from your website is:

The question is how to update this flow so that we can properly compute sales tax but not have to significantly rework proven processes or request changes of the payment processor. With TaxCloud.js this flow is virtually unaltered, except for the following minimal enhancements:

The red arrows represent TaxCloud interactions that complete sales tax requirements and are easy to implement. The executive summary is:

Ask TaxCloud for the proper tax on a group of items given a merchant origin address and a customer shipping address.

Notify TaxCloud that the purchase has been made.

This is the concept, now let’s take a deeper dive into exactly how to do it. For this example we will be using the following:

checkout.js – a library provided by Stripe to handle purchases with a credit card

jquery.min.js – everyone knows about JQuery, right?

HelloTaxCloud.html – a sample page using everything described in this post

As I mentioned earlier we will be using the built-in UI cart that taxcloud.js supports. The goal of this is to make things as easy as possible for web masters to show a cart of items with their tax as a line item. Our sample page uses this option, covers everything described in this post, is a little over 100 lines in length and works. Download the HelloTaxCloud.html page and take a look at it. If you put HelloTaxCloud.html on your web server you can step through all the concepts described here at your convenience. Don’t worry, when you start with TaxCloud your account is in test mode. It doesn’t become live until you say so!

Act 1: The Setup

First thing we need to set up is the proxy page/script that will run on your web server. We have two flavors for you to choose from:

If you are using another server processing extension you can either create the same page functionality on your platform (nothing tricky going on) or let us know so that we can create it.

Open TaxCloud.php/TaxCloud.aspx in your editor and take a look at it. This file has two purposes:

It holds your credentials for TaxCloud and USPS

It receives posts from our taxcloud.js library running in your domain and forwards the data to our TaxCloud web service running in our TaxCloud.net domain.

While you have TaxCloud.php/TaxCloud.aspx open, lets go ahead and add your unique credentials.

The credentials you need are from your TaxCloud account, specfically your apiLoginID and apiKey. Log into TaxCloud and go to the Websites Section. Select your website, and your ‘API ID’ and ‘API KEY’ will be displayed.

The uspsUserID is an identifier that the US Post Office provides you so you may verify addresses. If you need a US Post Office user ID for shipping address verification you can get one by registering for USPS Web Tools.

Note that we are including with ‘https’ because we are doing a purchase page. Payment processors usually have this requirement. In fact, as we are demonstrating integration with Stripe, we need ensure https per their requirements:

Of course, if your site already uses a JQuery UI Theme, you can omit this link, and the TaxCloud.js UI will look like the rest of your site automatically.

Now we will look at the actual javascript code we need to add to make all this work. This seems like a good spot to introduce the TaxCloud objects defined in taxcloud.js. They are:

TaxCloudConnection — this handles the actual network communication between the web page and TaxCloud (via TaxCloud.php/TaxCloud.aspx).

TaxCloudAddress — this class makes it easy to use a shipping address with both the US Post Office (for verification) and TaxCloud (for tax lookups)

TaxCloudCartItem — represents an item in your cart a customer can purchase. It has a price, quantity and Taxability Information Code (TIC). [You will need to be logged-in to review complete TIC documentation]

You can also see that we have defined a javascript variable “storeName” – you should set this to the name of your store, which will be seen by your customers in the checkout UI titlebars.

After initializing TaxCloud, we use JQuery’s ready() to register an event and finish “installing” taxcloud on your HTML page.

TaxCloud has several events you can hook into during the processing of the address and cart. We’re keeping it simple here and just wiring up the ‘OnPurchaseStep2PurchaseClicked’. This notifies you that the customer has completed the cart steps (provided their shipping address and looked up their tax information) and therefore a ‘Grand Total’ is available. You will respond to this event by grabbing that grand total and beginning your purchase process (for example, with a credit card).

The last line in this code snippet sets the unique customer id for the end user. The customerID is a field you supply that uniquely represents the customer. The function also takes a flag that tells TaxCloud whether or not to retrieve previous address and cart information, if found. This handles the case where people start a purchase, cancel it and then return later to pick up where they left off. Right now we only store this information for 24 hours. You can use this customerID later to view customer specific transactions in our activity log. The customerID field is required.

Fabulous, TaxCloud.js is now installed and ready to go to work.

Act 3: Where are you?

We have one more step before you can get onto the business of selling things. You need to tell TaxCloud.js what your address is (your store or office location). Note: This location must also be added to the TaxCloud website, in the Locations section.

Act 4: The Products

Next we need to let TaxCloud know what the items are that we will be checking tax information for. This means we need to create a TaxCloudCart with a list of TaxCloudCartItem objects. Each TaxCloudCartItem object has five properties:

an item identifier (a SKU works great) but we do not recommend using a title or product name – this identifier is for machine use, not human use

the item display name or brief description – this one is for human use

the unit price

a quantity

a TIC (remember that Taxability Information Code?)

You can add TaxCloudCartItems to the TaxCloudCart one at a time or in bulk. For example, to add a single item at a time you could create a button as follows:

The ‘onclick’ handler adds the new TaxCloudCartItem to the TaxCloudCart, which triggers an internal event so that it immediately appears in the UI. Then the ‘onclick’ handlers does a Lookup to update all the line items in the cart, including the new one we just added.

Act 5: The Customer

Once we have the origin address and the cart in place we need to get the shipping address, verify it and do the tax lookup. Here we will make use of the taxcloud.js built-in UI to display an address form the customer can fill out. We respond to a click event on the page to start the purchase flow. In this case I created a standard button that a JQuery handler will catch the ‘click’ event for. I named it with id=’TaxCloudPurchaseButton’, but you can call it anything you like.

When a user clicks the button identified by ‘TaxCloudPurchaseButton’, it fires the javascript code above and TaxCloud.js initiates the UI.

Specifically, it calls ‘OpenPurchaseStep1()’. This tells the TaxCloud library to use its built-in UI components. Once this call is made the following UI pops up to obtain the customer’s shipping address.

This form will be filled out by the customer and represents their shipping address for all the items in the cart. The button at the lower-left lets them know the ‘state’ of their address. That is, if its verified or unverified. At this point, you can click on the USPS verify address button if your want to check what you have entered, but it is not necessary because TaxCloud.js does this automatically when you press ‘Next’. So, let’s enter an example shipping address to work with and click ‘Next’ to go to our second page.

Now we see all the items in our cart. Lets talk for a moment about what else is going on here. You can see now that the address has been verified (or verification failed). You don’t need to have a verified address in order to complete a purchase, but a verified address will ensure the most accurate sales tax rates.

After attempting to verify the address, TaxCloud.js proceeded to lookup the correct sales tax amount due for each item in the cart. These calls happen asynchronously, which means the customer may see the sales tax amounts appear/update in the cart.

We also see each item listed with a unit price, the current quantity, the line item price, the line item tax amount and the line item total (price + tax). Finally, just above the ‘Update’ and ‘Purchase’ buttons we have the total, which is the sum of price and tax for all line items.

This form is interactive as well in that the customer can change quantity amounts and everything will be looked-up and computed again. Simply adjust a quantity and either click in another field to trigger the update, or click the ‘Update’ button. The new prices and tax amounts will be changed in the screen when the asynchronous calls receive their response.

At this point you may be curious what code you need to add in order to handle the transition from the first purchase page to the second. The answer is, there is none. The TaxCloud library, being UI aware, handles this transition for you. We do make callback hooks available if you require additional processing before proceeding, but we’re keeping things simple for the time being. In a future post we will look at all the TaxCloud UI events available. One event we do need to hookup is when the customer clicks the ‘Purchase’ button. For that action we have the following event hook and callback example:

Act 6: The Purchase

We told the TaxCloud library what call to make when the purchase button on the second page is clicked. TaxCloud will call this method and pass in an instance of itself as the parameter. This is where you, the merchant, can do extra processing if needed before making the actual purchase. In this test case we have a small but important processing step to do. Stripe requires purchase amounts to be in cents, so we multiply the ‘myTaxCloud.cart.GrandTotal()’ by 100.0 and send that that amount to our Stripe purchase handler. Additional processing steps don’t have to be complicated to be important!

So what does the Stripe purchasing code look like? Our implementation looks like this:

Note: You will need to log into Stripe to find your API Keys, as pictured.

There are three global functions and one embedded function in the code snippet above. Let’s talk about what each one is doing.

purchaseWithStripe(myTaxCloud, grandTotal)

This function is responsible for building form data, creating a Stripe token and showing the Stripe ‘Checkout’ dialog. Similar to how TaxCloud manages the two purchase step pages, Stripe provides a javascript library that pops up a nice credit card entry form.

Once this form has been filled out we use the Stripe library to create a special, proprietary Stripe token.

Next we use the TaxCloud.Purchase method to send this data to Stripe via another proxy page (in this case another page we created using Stripe’s PHP library). This method simply takes a page to post form data to, the actual form data to post and a callback function. Once the data is posted and the response is received, the callback function is invoked. In this case it was:

purchaseWithStripeCallback(myTaxCloud, responseText)

The responseText is the actual data returned from Stripe. TaxCloud will treat this as opaque and hand it to you as a parameter in the callback. With Stripe this happens to be JSON data we can turn into a javascript object. Now we have TaxCloud data and Stripe data available to issue, if the purchase was successful, the final call in our flow:

myTaxCloud.authorizedWithCapture

This function lets TaxCloud know that the transaction is finished and approved. As a result, TaxCloud will add it to your monthly sales tax report. IMPORTANT: This is a mandatory API call for TaxCloud.

The method itself takes an orderID that you supply (in this case I’m using the Stripe purchase ID so that I can cross reference easily), an authorized date, a captured date (which can be the same) and the callback to invoke when the authorizedWithCapture web service call to TaxCloud returns.

Finally, upon that last callback we tell the customer the good news. You may want to add a bit more to this step.

This is our first iteration with TaxCloud.js and we are excited to hear your feedback as to how to improve it. Our goal is to make calculating sales tax as easy as possible for everyone – at no cost.

One last thing

Congratulations are in order! You have successfully integrated real-time sales tax for your customers – and you probably did it in less than an hour. Now that you have completed a transaction with your account in test-mode, you should return to TaxCloud, go to the Websites section, and click Go Live. This is important so that TaxCloud can begin preparing your monthly sales tax reports – and in 24 states, TaxCloud can even file your returns and remit your sales tax proceeds for you (with more states coming soon).