Skip to main content
Avalara Help Center

Install CertCapture for eCommerce

This article applies to:Avalara CertCapture

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 API Documentation.

1.png

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.

Things you'll need:

  • Access to an existing CertCapture environment  
  • A web developer or site administrator that can integrate the eCommerce SDK with your website
    • REST API experience
    • JavaScript experience 
  • Access to the CertCapture API is recommended 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. Used 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

Unique username and password for the eCommerce integration. Used as the Basic Auth credentials for the Get Token API call.

Create these 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 A customer's state, jurisdiction, or custom exposure zone.

Generating a token

An authorization token must be requested for each customer record in CertCapture before the eCommerce plugin can be launched. You'll reference an API endpoint in our CertCapture REST API documentation. See the Get Token API documentation for instructions for generating a token with Java, Python, PHP, and other languages. 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. 

2.png

Basic eCommerce workflow

All eCommerce workflows require a ship zone and token. 

<!-- 
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>

Plan your integration: eCommerce workflow decision points

3.png

Decision 1: Location - Add the eCommerce SDK to an Account Page

Add the eCommerce integration to 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.

Note: Access to the CertCapture 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. While API instructions and endpoints are available, your web developer must create any additional buttons, fields, tables, or other UI elements.

A representative example is shown below. In this example, a customer can update their certificate using the eCommerce SDK or download their certificate using the CertCapture API. By using the CertCapture API to fetch info like Signed or Expirate date from the customer's record, returning customers are able to view exemption status at any time.

4.png

Decision 2: Handling Customer Data

A customer number is the unique identifier for the customer record 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 be passed via the eCommerce SDK whether the customer is new or returning. 

Autopopulating customer data

  • If your customer's contact details are already stored in your website, use the example code below to populate that customer data.
 <!-- 

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'
        //Customize colors of buttons
        primary_color: '#ff6600',  
        secondary_color: '#ff6600'
    });
    
    //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>

Creating multiple certificates

  • If your customer has several jurisdictions and certificates to submit, separate the states as shown in the example code below.
<!-- 

Passing ship_zone with multiple exposure zones/states separated by "|" 
will start the workflow for creating multiple certificates

-->

<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|California",
      token:'token generated from your web application server'
    });
    GenCert.show();
    

  </script>
</body> 

Note about Nexus: A customer's shipping address may lie outside of your nexus for certificate collection. You can communicate that to the customer on your account page to prevent unnecessary certificate creation.

Decision 3 - Certificate Validation and Exemption Status

Validation:

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.

New certificates are automatically validated, unless this behavior is altered using the "submit_to_stack" function, shown in the code below and described in the Index at the bottom of this article. Automatic validation allows users to make exempt purchases right away, but creates the potential risk of an invalid certificate that must be corrected later.

Note: While new certificates filled out using the eCommerce SDK are automatically validated, imported certificates aren't.

  • In the below example, an exemption is automatically validated and applied.
<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>

Submission Confirmation: Callback functions

Customers should receive some form of feedback following a successful or failed submission. Callback Functions are optional actions that can be triggered by certain steps during an eCommerce workflow. See the Index at the bottom of this article for a full list of callback functions.

  • In this example, a window alert is triggered following a successful submission.
  • 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>

Decision 4: Exemption Status and Returning Customer Info

Use a GET API call to return a customer's exemption status. Refer to the CertCapture API documentation for a full list of options for retrieving customer data. Incorporate this information in your account page to save your customers time.

Customers can edit their exemption information during a return visit. Allow customers to update contact information on their own when details change.

  • In this example, the edit_purchaser function allows the customer to edit their info during the eCommerce workflow.
<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'
      edit_purchaser: true
    });
    GenCert.show();
  </script>

 


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.

Passing a customer object during initialization for an existing customer record

Sending customer object details that are new for an existing customer doesn't overwrite the existing data. 

Special certificate types

Multi-jurisdictional 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

If a certificate only covers 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.

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
onCancel 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 After constructor has finished loading
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
onCertSuccess After submission, when certificate is successful.  Access the generated certificate id with "GenCert.certificateIds"
onCertFailure After submission, when certificate is failure
onCancel User cancels the certificate generation process
onNotNeeded Called when a Zone that does not charge sales tax is chosen

General Functions for additional customization

submit_to_stack

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

Default is false.

preview

Allows user to quickly view their new certificate so they can save or print it. Certificate is not generated in CertCapture.

Default is false.

customer_list

Appends a page to the generated file that includes "Customer Number", "Customer Name", and "Customer Address" of each customer associated with the certificate. Must be called at initialization of GenCert API.

Default is false.

upload_only

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

Default is false.

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

Displays a download link after document submission. 

edit_purchaser

Allows the customer to edit their information on return visits. To allow customers to edit their existing information, use edit_purchaser: true. 

Default is false. 

setCustomerData(customer)

Sets form prefilled with customer data. Function must follow the standard convention below:

GenCert.setCustomerNumber('CustomerTestGencert4'); 
// 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); 
GenCert.setShipZone('California');

setCustomerNumber(custnum)

Sets the form unique identifier for customer number, to identify the customer to which the certificate should be applied.

Parameter custnum should be an alphanumeric unique identifier for the customer filling out the form.

The customer number must be supplied via the constructor option or this function. 

setShipZone(zone)

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

This is not the customer’s ShipTo state.

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 via the constructor option or this function.

show() Shows the form in the parent container.
hide() Hides the form in the parent container.

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?