Avalara AvaTax with Stripe.js

The new AvaTax.js library makes it easy to calculate taxes with browser-based shopping carts and other web commerce environments — providing real-time tax calculation results during the checkout process. Those accurate, on-demand tax calculations can be consumed at time of checkout, allowing you to display the results to your shoppers or use them in your payment processing. This diagram is a typical process flow for an E-commerce scenario.

E-Commerce Workflow with Stripe integration

Let’s take a look at an easy example where AvaTax.js can be used in conjunction with Stripe.js to calculate tax and create a payment authorization token.

You’ll need to include the core files (AvaTax.php and AvaTax.js) available here in your site directory.

1. Enter your AvaTax account credentials in the AvaTax.php proxy file. If you don’t have an AvaTax account yet, you can sign up for a free trial account.

$accountNumber = "1234567890";
$licenseKey = "A1B2C3D4E5F6G7H8";

2. Include the AvaTax.js reference in your page.

<script type="text/javascript" src="AvaTax.js"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>

3. Call the methods provided to calculate tax. The request parameters in your actual call should be values drawn from the cart on which you want to determine tax.

var getTaxRequest = {
customerCode: "ABC4335",
docDate: "2014-01-01",
companyCode: "APITrialCompany",
client: "AvaTaxSample",
docCode: "INV001",
addresses: [
{
addressCode: "01",
line1: "45 Fremont Street",
city: "San Francisco",
region: "CA" }],
lines: [
{
lineNo: "01",
itemCode: "N543",
qty: "1",
amount: "10",
originCode: "01",
destinationCode: "01",
description: "Red Size 7 Widget"}]};

4. Consume the calculation results

If the order has not yet been placed, and you’re just estimating the tax amount prior to confirmation, you might have something like this:

GetTax(getTaxRequest, displayTaxToUser(getTaxResult));

Otherwise, if you’re recording an order to AvaTax that has been confirmed, and you’d like to charge the card as well, you might do something more like this:

GetTax(getTaxRequest, function(getTaxResult) { chargeCardViaStripe((getTaxResult.TotalTax + getTaxResult.TotalAmount) *100 )});

And you’re done!  That one GetTax call can be used to calculate tax on a cart and/or to record a finalized order in the AvaTax™ system for reporting and filing. For more examples of calls using the AvaTax.js library, take a look at the test html files available in the JavaScript sample repository.

 

AvaTax.js sample posted!

There’s a new sample posted for folks working in JavaScript! This sample uses a server-side PHP proxy to call the service, making it easier to calculate accurate taxes and record documents from browser checkout environments. Check it out and let us know what you think!

 

Avalara Avatax REST SDK for iOS now available!

If you’re building mobile related retail applications or extensions to your ERP/Ecommerce platforms on iOS for the iPhone or iPad, then you’re in luck. We just completed the iOS Software Development Kit that allows you to easily connect to Avalara’s Avatax API. The SDK comes as a static library that you can link to your iOS projects. For REST de/serialization, we’ve used a 3rd party library called JSONModel which simplifies data transformation from object model to JSON (and back). We’ve included that into the project as well as the full source code under the Apache 2.0 license.

You can download the SDK and others from our Sample Code Library.  Please feel free to try it out and give us some feedback.

 

Prompting users for certificate information with the AvaTax Certs API

The AvaTax Certs product is a stand-alone exemption certificate management product that can be used in conjunction with the AvaTax Calc product. The Certs product allows a company to track exempt customers, initiate automated correspondence to request certificate information from those customers, and track and manage the resulting exemption certificates. All valid certificates created/recorded in the AvaTax Certs product sync over to the AvaTax Calc product as well – once a customer has a valid exemption certificate in Certs, they will automatically be tax exempt for your tax calculations.

There is a RESTful API to interact with the AvaTax Certs objects. That API documentation is password-protected. If you have an AvaTax Certs portal account, that same credential set will grant you access to the API documentation.

Note that the AvaTax Certs product is currently being combined with the CertCapture product, but this article uses the resource terminology specific to the AvaTax Certs API.

If you are interested in flagging your customers as tax exempt within the AvaTax Calc product (and not in using an additional certificate management product), take a look at this summary of managing exempt customers.

Okay, now let’s get down to brass tacks. You have a customer who is buying things on your website and wants to let you know that they are tax exempt. Here’s a diagram of the recommended workflow (with API calls):

AvaTax Certs Workflow

*If you’re using the AvaTax Calc product to calculate tax, it will reflect the existing exempt status for the customer.

** The wizard URL is just www.vcert.com/<certificate-request-id>, where the certificate request ID is the unique request identifier returned in the Org-Requests POST response. Note that if a customer already has an open certificate request, Org-Requests POST will return an error, and that existing request ID can be retrieved with Org-Requests GET.

This workflow will cover the following starting cases:

  • The customer record does not yet exist.
  • The customer record exists, but has no certificates and no open certificate request.
  • The customer record exists and has an open certificate request.
  • The customer record exists and has one or more expired/revoked certificates and no open certificate request.
  • The customer record exists and has one or more valid certificates.

Once a customer has filled out their exemption information, their order can be processed per your business use case.

Handling Java SSL Certificate Exception

If you are trying to make an HTTPS call to the AvaTax web service from a WebSphere Message Broker  and recieve an exception message similar to below, it is likely that the Message Broker is unable to build the entire certificate path. The Message Broker “keystore” must have all of the certificates in the “chain” of CA’s.

javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.h: PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is: java.security.cert.CertPathValidatorException: The certificate issued by OU=Class 3 Public Primary Certification Authority, O=”VeriSign, Inc.”, C=US is not trusted; internal cause is: java.security.cert.CertPathValidatorException: Certificate chaining error

One way to verify that all of the required certificates are in your keystore is using the “keytool” from the bin directory of the interface in use.

  1. Start an Administrator Command Prompt.
  2. Navigate to the bin directory of the API method you are using.
  3. Type keytool –list and review the certificates stored. You should see at least one Verisign certificate authored by Avalara with an expiration date greater than the current date.
  4. If not, you may need to recreate the keystore with ‘keytool’ using the “genkey” option and re-import your application certificates if any of the components of the certificate chain are missing or out of date.

Search http://www-01.ibm.com/support/ for “keystore” or “keytool” or “genkey” for more information.

Note:  If you are using a Microsoft Windows environment, Certificate Manager (CertMgr) can be accessed via your devices Management Console. You will need administrative rights to use this tool.

Testing Address Errors

When you’re testing your integration, it’s always a good idea to figure out how you’re going to handle errors. Not all errors from our system are bad – some just mean a user has entered an invalid address (perhaps by making a typo!) – and your system should react accordingly. These address-related errors are to be expected in normal use of your connector.

Sometimes it can be challenging to create this use case on purpose: our system is very good at validating addresses and calculating tax accordingly (albeit at lower precision levels). In fact, due to customer demand, we recently updated the service to allow tax calculation on zip5. This is not always the most accurate tax, but if your business only collects zip codes, we’ll give you something to work with.

If you’re looking for an error case, here are some good ways to create one:

Let’s start with a real, valid address. Our address is:
100 Ravine Ln
Bainbridge Island, WA 98110

By changing enough elements, we eventually return JurisdictionNotFoundError in the GetTaxResult. Let’s start with the address line:

1000 Ravine Ln
Bainbridge Island, WA 98110

There is no 1000 on Ravine Ln, but that alone won’t fail tax calculation because city, state and zip is enough.

1000 Ravine Ln
Bainbrid, WA 98110

I truncated the city too, but even that still returns tax because state and zip is sufficient to determine a tax region.

1000 Ravine Ln
Bainbrid, WA 43256

When I change the zip, it returns the error, because there just aren’t enough matching elements for the system to find the location. Finally, our error! By moving through each address element in turn, we get a better picture of how Avatax uses elements in the tax calculation, and its threshold for bad addresses. Of course, if you want to just go for it, you can always generate an error by making sure that none of your address elements match:

521 Totally Bogus Parkway
Tacoma, CA 11111

Reflecting MDET

At the beginning of 2013, a new federal-level excise tax was introduced for some medical devices. If you have clients that need to reflect this tax, make sure you’re doing the following:
1. Allow clients to pass a product tax code.
2. Allow clients to assign an Entity/Use Code (CustomerUsageType) to their customers.

The combination of product tax code and customer entity/use code allows your client to trigger specific rules in their company profile, and calculate this tax. If you’re using service version 13.1 or later, you can parse out this tax from your GetTaxResult as well – it will come across as a TaxDetail element with TaxType of Excise and JurisType of Country.

Updates to REST tax/get POST with 13.3. release

Some long-awaited additional parameters have been added to the tax/get POST request with the recent 13.3 release. These parameters are now available on both development and production for all clients using the REST API. With this update, the REST API is now in full best-practice parity with our SOAP API. For more information, see the tax/get POST documentation.

  • PosLaneCode
  • Client
  • BusinessIdentificationNo
  • TaxOverride