Skip to main content
Avalara Help Center

Install CertCapture for eCommerce

This article applies to:CertCapture

Learn how to embed CertCapture's document submission form into your online store so customers can manage their exemption certificates before or after making a purchase. Use the functions and script examples provided in this article to customize the user experience.

There's a lot of information on this page. Use the Table of Contents on the right to skip to a specific section.

Use case: account page integration

This page provides context and instructions for integrating CertCapture with an account page on your online store. If you're new to using CertCapture outside of the web application, read the CertCapture API Getting Started guide.

This approach allows customers to manage their own certificates, minimizes communication with support, and avoids interruptions to the checkout experience. Your returning customers can view their exemption status and any other data that may be helpful from their online account settings. Using the CertCapture API, customers can download or update copies of their certificates.

Getting started

Things you'll need

  • Access to an existing CertCapture account
  • A web developer or site administrator that can integrate the eCommerce SDK with your website. The developer will need:
    • REST API experience
    • JavaScript experience 
  • Access to either the CertCapture or AvaTax API is required to generate an authorization token.
    Using additional API endpoints is optional, but strongly recommended. This allows you to enhance the customer experience on the eCommerce website.

Important: Avalara does not recommend storing API credentials in JavaScript. For the security of your customer's data, use a server-side implementation. Consider generating tokens from your web application server. Node and JavaScript examples in this article should be used for reference only. 

Required components for initializing an eCommerce workflow:

Client ID (Company ID)

This identifies your CertCapture environment, and you'll use it in the Get Token API call.

API documentation may refer to this as the client ID, but it is listed in the CertCapture UI as a company ID.

Find it in CertCapture at Settings > Company Settings > Company Details > Company Information.

eCommerce username and password

To begin, you must create a unique username and password for the eCommerce integration. This is not the same as the username and password that you use to log in to CertCapture. Used as the Basic Auth credentials for the Get Token API call.

Set the username and password in CertCapture at Settings > Company Settings > Company Details > eCommerce Settings.

Customer Number CertCapture identifies customers by their unique customer number. These are passed in the Get Token API call.
eCommerce Token

A token generated using the username, password, client ID, and a customer number stored in CertCapture. Must be passed for each eCommerce SDK initialization. 

Note: The generated token expires after 1 hour. 

Ship Zone The state, jurisdiction, or custom exposure zone to which the certificate applies.

Generating a token

Before you can launch the eCommerce plugin, you'll need to send an API call to request an authorization token. You must generate a separate authorization token for each customer in CertCapture. The token can be generated using either the CertCapture or the AvaTax API:

Try generating the token and combining it with various parameters at the eCommerce Plugin Demo on developer.avalara.com. Once the token is created, place the returned token value for that customer record in the token field in the eCommerce SDK code. 

Basic workflow

This section covers the simplest possible code snippet you can use with the eCommerce integration. The code snippet below includes only the required fields: 

  • Ship zone: The state or province to which the exemption certificate applies.
  • Token: The authorization token you generated in the previous section.
<!-- 
Required fields: 
    1. Exposure zone/state passed in the "ship_zone"
    2. Token
-->

<script src="https://app.certcapture.com/gencert2/js"></script>

<body>
  <div id="form_container"></div>
  <script>
    GenCert.init(document.getElementById("form_container"), {
    ship_zone: "[State, jurisdiction, custom exposure zone]"
    token:'token generated from your web application server'
    });
    GenCert.show(); 
    
  </script>
</body>

With this configuration, the user is guided through the process of adding an exemption certificate. The certificate is added as a valid exemption certificate in your CertCapture account, and in most cases the customer can make an exempt purchase right away.

This basic configuration is a good option if you want your customers to create a new exemption certificate each time they make a purchase on your eCommerce platform, and to be able to make exempt purchases right away. If you'd prefer to manually validate the certificates or let your customers view their existing exemption certificates, continue to the Customize Your Workflow section.

Customize your workflow

If you want to customize the workflow, you can do so by using a combination of the eCommerce plugin and CertCapture or AvaTax APIs.

Handling customer information: Name, address, contact information

A customer number is the unique identifier for the customer stored in CertCapture. If your customer database contains customer identification numbers, we recommend matching the customer numbers across your store and CertCapture.

Customer numbers should always be passed via the eCommerce SDK whether the customer is new or returning, but you can decide how you want to handle the other customer information (such as name, address, and contact information). The following approaches are the most common:

  • Do not send customer information when you initialize the eCommerce plugin:
    • New customers are prompted to enter their name, address, and contact information.
    • Existing customers use the information that you already have on file in CertCapture.
      If you want to allow customers to edit their information, use the edit_purchaser function.
  • Auto-populate customer information (recommended): If your customer's contact details are already stored in your website, use the example code below to populate that customer data.
    • Sending customer object details for an existing customer does not overwrite the existing customer details. Use the edit_purchaser function if you want to allow your customer to update their contact information.

Example code with a Customer Object:

 <!-- 

The Customer Object is prepopulated with existing data and passed into GenCert when initialized 

-->

<script src="https://app.certcapture.com/gencert2/js"></script>

<body>
  <div id="form_container"></div>
  <script>
  
    GenCert.init(document.getElementById("form_container"), {
        token:'token generated from your web application server'
    });
    
    //Create Customer and assign contact info automatically when loading Ecom SDK
    GenCert.setCustomerNumber('Autopopulate customer data'); 
    customer = new Object(); 
    customer.name = 'Autopopulate customer data';
    customer.address1 = '123 Test Street'; 
    customer.city = 'Durham';
    customer.state = 'North Carolina';
    customer.country = 'United States';
    customer.zip = '27701';
          
    //Sends Customer info to Ecom SDK
    GenCert.setCustomerData(customer); 
    
    //Sends Ship-To State
    GenCert.setShipZone('North Carolina'); //Sends Ship-To State
    
    //Opens the Ecom SDK
    GenCert.show(); 
    
  </script>
</body>

Decide where to add the eCommerce integration

Decide where in the eCommerce workflow you want your customer to provide their exemption certificate. The two most common sections are:

  • Checkout: The customer is given the option to add an exemption certificate during the checkout process.
    • This is the simplest workflow, and can be accomplished without using additional API functionality.
    • See the Basic Workflow section for more information.
  • Account page: The customer can navigate to a My Account page where they can view the status of any existing exemption certificates they have on file.

Note about Nexus: A customer's shipping address may lie outside of your nexus for certificate collection. If you don't want to collect exemption certificates for regions where you're not collecting tax, you can communicate that to the customer on your account page to prevent unnecessary certificate creation.

Use eCommerce plugin general functions to customize workflow

The eCommerce plugin includes a number of built-in functions that allow you to customize the certificate submission workflow. Since these functions are built into the eCommerce plugin, they do not require you to use the API. See the eCommerce Plugin General Functions section below for a list of all available general functions

A common use case for these general functions is using the submit_to_stack function to control the status of the exemption certificate once the customer submits it.

CertCapture dictates which fields on a certificate are available or required, but it can't validate the data within the fields automatically. Newly submitted certificates can be sent to a queue for review by a user in your CertCapture account or validated automatically. Decide how you want to handle certificate validation and exemption status:

  • Automatic validation (default): New certificates are automatically valid, which allows your customers to make exempt purchases right away.
    • This can create the potential risk if your customer submits a certificate that is missing information or is otherwise invalid. In this case, you would need to correct the issue later
    • If the state or jurisdiction prohibits the completion of a form online and requires the buyer to submit a copy of their state issued license or similar, the document is sent to the certificate validation queue and must be manually validated. 
  • Manual validation: Use the "submit_to_stack" function, shown in the code below and described in the Index at the bottom of this article. This sends the certificate to your certificate validation queue in CertCapture, and the customer is not exempt until you manually validate the certificate.

In the below example, an exemption is automatically validated and applied, because submit_to_stack = false.

<script src="https://app.certcapture.com/gencert2/js"></script>

<body>
  <div id="form_container"></div>
  <script>
    GenCert.init(document.getElementById("form_container"), {
      ship_zone: "California",
      token:'token generated from your web application server' 
      submit_to_stack:false
    });
    GenCert.show();
    
  </script>
</body>

Use callback functions Submission Confirmation: Callback functions

Callback functions are optional actions that can be triggered by certain events during the eCommerce workflow. This can include custom messages in specific scenarios, or redirect behavior (such as redirecting the customer to a My Account page if a certificate can't be generated). Callback functions are built into the eCommerce plugin, and do not require use of the API. See the Callback Functions section below for a list of all available general functions.

Customers should receive some form of feedback following a successful or failed submission. For example, you might decide that you want to display a message after the user has submitted an exemption certificate. 

  • In this example, the onCertSuccess callback function is used to trigger a window alert following a successful submission.
  • Also in this example, the onUpload callback function is used to trigger a window alert following a successful upload.
  • Keep in mind that submission of a certificate does not guarantee a valid certificate.
<script src="https://app.certcapture.com/gencert2/js"></script>

<body>
  <div id="form_container"></div>
  <script>
    GenCert.init(document.getElementById("form_container"), {
      ship_zone: "Alabama",
      token:'token generated from your web application server' 
      
      onCertSuccess: function() {
          window.alert("Successful creation"); 
      },
      onUpload: function() {
          window.alert("Successful upload."); 
      }
    });
    GenCert.show();
  </script>

Advanced workflow using APIs

If you're not able to achieve the workflow you want by using eCommerce plugin general functions and callback functions, consider using the AvaTax or CertCapture APIs to add more functionality.

A warning icon

Access to either the CertCapture API or the AvaTax API is required to fully incorporate all CertCapture data for the customer record with your website. Avalara does not provide a standard template for a detailed account page. API instructions and endpoints are available, but your web developer must create any additional buttons, fields, tables, or other UI elements.

A common example of using the APIs to add more functionality is to integrate the eCommerce plugin with an Account Page so customers can upload exemption certificates and view exemption status or certificate details. Once exempt, customers can avoid submitting new certificates for each purchase as long as their certificate is still valid. We recommend placing the eCommerce SDK outside of the checkout workflow to avoid confusion or complexity in the checkout cart. 

The simplest integration is using a button or hyperlink on the customer's Account Page. Customers use this to create or upload a certificate before they begin a potentially exempt order.

A representative example is shown below. In this example, a customer can add a new certificate or renew an existing certificate using the eCommerce SDK. The other options utilize data retrieved through an API call. Using the API to retrieve this additional information is recommended, because it allows returning customers to view their exemption status at any time.

There are a number of API endpoints available, but the following endpoints are the most commonly used with the eCommerce plugin:

  • Retrieve customer information: Use this API endpoint to retrieve your customer information, including name, address, and contact information.
  • Update customer contact information: You can let customers update their contact information using either the edit_purchaser function, or by sending an API call.
  • Retrieve certificate information: Use this API endpoint to retrieve a list of the certificates that you have on file for the customer.
    You can use this information to populate a list of certificates and exemption statuses for the customer, so they know when they need to provide a replacement for an expired or invalid certificate.
  • Retrieve certificate PDF: Use one of these APIs to retrieve the binary data for the PDF, which you can then convert to a PDF.

For additional endpoints, see the CertCapture API documentation and the AvaTax API documentation.

Customize the colors of the plugin

The primary color and secondary color of the eCommerce plugin can be customized using the primary_color and secondary_color functions:

<script src="https://app.certcapture.com/gencert2/js"></script>

<body>
  <div id="form_container"></div>
  <script>
    GenCert.init(document.getElementById("form_container"), {
    ship_zone: "[North Carolina]"
    token:'token generated from your web application server'
    //Customize colors of buttons
    primary_color: '#ff6600',  
    secondary_color: '#ff6600'
    });
    GenCert.show();
    
  </script>
</body>

Additional visual customizations are not supported.


Index

Common errors / FAQ

"You do not have exposures to exempt at this time" error on SDK initialization

Check the spelling of the ship_zone field being passed. Also, check the nexus settings in CertCapture. The SDK will return this response when the ship_zone is not in the nexus for that company in CertCapture.

Upload and deletion of certificate PDFs via API

Loading certificates through an API POST is not recommended as the certificate should be validated or created through the controlled settings within the eCommerce interaction. Use the built-in functionality of the eCommerce plugin instead of passing PDFs via the API.

Special certificate types

Multijurisdictional certificates

CertCapture's exemption matrix controls the certificate that is presented during an eCommerce workflow. A customer presented with a multijurisdictional certificate can complete one certificate to cover multiple jurisdictions. Determine how best to handle additional jurisdictions during validation and what information to display when retrieving customer exemption status.

Single Use certificates

If a product or service only allows for a single use certificate, the site must call for a new certificate each time instead of using the API to retrieve the customer's status.

Exemption Percentage certificates for utility companies

If a certificate exempts only a portion of the total tax, the site must calculate that percentage following certificate submission. The percentage of exemption can be documented during the validation process but it can't be automatically loaded into a tax engine for calculation.

  • This function is applicable only for certain electrical utility purchases with the support of an approved engineering use report.
  • This does not apply to certain states reduced sales tax forms, such as California manufacturing exemptions.
  • Exemption percentages are not compatible with AvaTax. You can store an exemption percentage for informational purposes, but it does not have any impact on tax calculation in AvaTax.

eCommerce plugin general functions

See below for a list of all of the available general functions.

submit_to_stack

Sends the new document to be validated in CertCapture at Manage Documents > Upload Documents.

Choose one of the following options:

  • False (default): New certificates are automatically valid. This allows your customers to make exempt purchases right away.
  • True: New certificates are submitted to your validation queue in CertCapture. The customer is not treated as exempt until you validate the document.

Note: If you use submit_to_stack: True, we recommend using the onInit callback function to display a message that lets the user know they may not be able to make a tax-exempt purchase immediately, since you must manually validate the certificate.

preview

Allows the user to see a preview of their new certificate before signing and submitting the certificate.

Choose one of the following options:

  • False (default): The user sees a blank copy of the exemption certificate, but does not see a preview of the certificate with their information.
  • True: The user sees a preview of the certificate populated with the information they've entered.

Note: The preview is a low-resolution GIF. If you want to provide the user with the option to download a high-quality copy of the certificate, use the show_files function instead

upload_only

Disables the ability to complete documents by submitting information to form fields. Customers can only upload prefilled documents.

Choose one of the following options:

  • False (default): The user is guided to enter their exemption certificate information, and CertCapture generates a new copy of the certificate.
  • True: The user must upload a scanned copy of their exemption certificate in one of the following file formats: PDF, JPEG, TIFF, PNG.

Note: If you use upload_only: true, the certificate is sent to your certificate validation queue in CertCapture and must be manually validated.

fill_only

Allows you to disable the upload of prefilled documents, so that users must generate a new copy of the certificate by entering their information.

Choose one of the following options:

  • False (default): The user is has the option of either uploading a scanned copy of their certificate, or generating a new copy of the certificate by entering their exemption certificate information.
  • True: The user is guided to enter their exemption certificate information, and CertCapture generates a new copy of the certificate.
    • The user is not able to upload a scanned copy of their certificate, unless the state requires them to upload a copy of their state issued license or a similar document.
show_files

Displays a download link after document submission. Avalara recommend setting this to show_files: true.

Choose one of the following options:

  • False (default): The user is not given the option to download a PDF copy of the exemption certificate.
  • True: The user is given the option to download a PDF copy of the exemption certificate.
edit_purchaser

Allows the customer to edit their information on return visits.

Choose one of the following options:

  • False (default): If you already have the customer added in your CertCapture account, the user is not able to update their name, phone number, or address. 
  • True: The user is able to update their name, phone number, and address. 
setCustomerData(customer)

Use this option to send customer information for new customers. Function must follow the standard convention below:

// create customer
customer = new Object();
customer.name = 'TEST NAME';
customer.address1 = '1300 EAST CENTRAL'; 
customer.city = 'San Francisco';
customer.state = 'CA';
customer.country = 'US';
customer.zip = '89890';
customer.phone = '555-555-5555';
customer.fax = '555-555-5555';
GenCert.setCustomerData(customer); 
// setShipZone if you haven't specified it in the GenCert parameters.
GenCert.setShipZone('California');
setShipZone(zone)

Sets the zone to which the transaction is shipping and/or where the certificate would apply.

This is not the customer’s state, per billing records, but rather the shipping state where the goods will be delivered. 

Parameter state should be a valid US or Canadian state/province in proper case, ex: ('California'). Does not accept lower case or upper case names.

The ship zone must be supplied in order for the system to create the proper form

show() Use this to decide when to show the exemption certificate completion form in your eCommerce platform. 
hide() Use this to hide the exemption certificate completion form once the user has completed the process. Hides the form in the parent container. 

Callback functions

See below for a list of all of the available callback functions.

onUpload    

    Called when a document is uploaded. Access the generated certificate id with "GenCert.certificateIds".

We recommend adding the onUpload function. If you don't, your customer won't know what to do after the certificate has been uploaded.

Example:

GenCert.init(document.getElementById("form_container"), {
      ship_zone: "Alabama",
      customer_number: "cc00001154",
      
      onCertSuccess: function() {
          window.alert("Successful creation");
      },
      onUpload: function() {
          GenCert.hide();
      }
    });
    GenCert.show();
onCertSuccess Can be overridden to perform a customized action such as user navigation after a certificate is successfully created. After submission, when certificate is successful.  Access the generated certificate id with "GenCert.certificateIds".
onCancel User cancels the certificate generation process. Used to reinitialize GenCert or provide user navigation. 
onManualSubmit Used to reinitialize GenCert or navigate the user elsewhere. This occurs when nexus (exemption matrix) is set to manually collect a document. The user can upload a form when this happens.
onInit Called when the plugin is first initialized.
beforeShow Called before the form is shown
afterShow Called after the form is shown
beforeValidate Before form validation
onValidateSuccess After form validation success, before submit
onValidateFailure After form validation failure
onCertFailure After submission, when certificate is failure
onNotNeeded Called when a Zone that does not charge sales tax is chosen

Customer data values

Prefilled customer data - inner JSON object with data string fields

customer   
          name       
address1
address2
city
state
country   
   zip
phone
fax
email

 

  • Was this article helpful?