Install CertCapture for eCommerce
Learn how to use a software development kit (SDK) to embed CertCapture's document submission form into your eCommerce platform or online store so customers can manage their exemption certificates before or after making a purchase. The SDK provides you with much of the functionality you'll need, but you should plan to work with a developer that has experience with JavaScript and REST APIs because this process does require some software development knowledge to customize the workflow.
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, you can use either the AvaTax API or the CertCapture API:
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.
Before you begin
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. |
|---|---|
| Script source URL |
|
|
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. Note: The eCommerce username and password must be set up separately for your Production and Sandbox accounts. |
| 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. |
Create an eCommerce username and password
|
|
Important This section is applicable only if you plan to use the CertCapture API endpoint to generate the authorization token. If you plan to use the AvaTax API endpoint instead, refer to the authentication section of the AvaTax API developer guide. |
Before you can use the CertCapture API to generate an authorization token, you must create an eCommerce username and password to use as the Basic Auth credentials for the Get Token API call. If you plan to use the eCommerce plugin in both sandbox and production, you must create the username and password separately in each account.
- In CertCapture, go to Settings > Company Settings > Company Details.
The Company Details page opens. - Select the eCommerce Settings tab.
- Select Manage eCommerce Account.
The Manage eCommerce Account menu opens. - Enter a username, email address, and password.
The username must be different from the username you use to sign in to CertCapture. - Select Save.
You can now use these credentials to authenticate the CertCapture Get Token API endpoint.
Getting started
Generate 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:
- CertCapture: See the Get Token API documentation for instructions for generating a token with Java, Python, PHP, and other languages. Use the eCommerce username and password you set in the previous section to authenticate.
- AvaTax: See the Create eCommerce Token documentation. Use an AvaTax username and password to authenticate.
Try generating the token and combining it with various parameters at the eCommerce Plugin Demo on developer.avalara.com. Alternatively, you can use an API client such as Postman to send the API call. Once the token is created, place the returned token value for that customer record in the token field in the eCommerce SDK code.
Understand the 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.
Decide how to handle 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.
|
|
The customer object doesn't accept abbreviations for state or country. Make sure to use the full state and country names instead of abbreviations. |
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.
- This workflow is more complex, and typically requires some combination of general functions, callback functions, and APIs.
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>
Understand advanced workflows 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.
|
|
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.
- CertCapture: See the documentation for the Retrieve a customer API.
- AvaTax: See the documentation for the GetCustomer API.
- Update customer contact information: You can let customers update their contact information using either the edit_purchaser function, or by sending an API call.
- CertCapture: See the documentation for the Update a customer API.
- AvaTax: See the documentation for the UpdateCustomer API.
- 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.- CertCapture: See the documentation for the Get certificates API.
- AvaTax: See the documentation for the ListCertificatesForCustomer API.
- Retrieve certificate PDF: Use one of these APIs to retrieve the binary data for the PDF, which you can then convert to a PDF.
- CertCapture: See the documentation for the GetCertificatePDF API API.
- AvaTax: See the documentation for the DownloadCertificateImage API.
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:
See this guide for more information. 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:
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:
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:
|
| show_files |
Displays a download link after document submission. Avalara recommend setting this to show_files: true. Choose one of the following options:
|
| edit_purchaser |
Allows the customer to edit their information on return visits. Choose one of the following options:
|
| 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 |
| onSaveCustomer | After the customer is saved |
Customer data values
Prefilled customer data - inner JSON object with data string fields
| customer | |
| name | |
| address1 | |
| address2 | |
| city | |
| state | |
| country | |
| zip | |
| phone | |
| fax | |