Skip to main content
Avalara Help Center

Install Avalara CertCapture for eCommerce

This article applies to:Avalara CertCapture

Embed CertCapture's exemption document submission form into your ecommerce site so it can communicate with CertCapture. Add the JavaScript tag to your application's webpage, and then use our list of functions to customize how the CertCapture submission form appears on your site.

We recommend contacting Avalara Professional Services before you set up CertCapture for eCommerce.

Requirements

  • An eCommerce API username and password
  • Basic understanding of JavaScript and custom scripting is required in order to customize functionality and process callback actions. The eCommerce SDK's GenCert API functionality is delivered through a JavaScript “script include” hosted by CertCapture. You need to reference this Javascript tag on any page that uses the API
  • To allow customers to edit existing purchaser information in CertCapture for eCommerce, the edit_purchaser function must be set to true. See Customize your script with functions

Generate a token and add the JavaScript tag

When using CertCapture for eCommerce, your website requests an authorization token from CertCapture before your customer can create an exemption document. To ensure uninterrupted communication between your ecommerce platform and CertCapture, your website administrator should construct the script used to launch the integration using the following information.

Review the API endpoint referenced in this tokenized integration in the CertCapture REST API documentation

  1. Sign into CertCapture and go to Settings > Company Settings > eCommerce Settings, and then click Manage eCommerce Account.
  2. Set your username and password, and then click Save
    • In the Email field, use the email address you used to sign into CertCapture
  3. Go to Settings > Company Settings > Company Details > Company Information and note the Client ID for the next step.
  4. Generate a token using the username and password you just created, and the Client ID. 
    • A customer number identifying the customer interacting with the ecommerce integration and your Client ID are required to build the token information
    • This API endpoint generates a JSON Web Token that facilitates security between CertCapture and your platform for each ecommerce customer that creates an exemption document. This endpoint must be called from your web application server to retrieve an authentication token for each ecommerce customer
    • Generate the token using the headers specified in the API documentation: x-client-id, Authorization, and x-customer-number
      • Example: 'x-client-id': '12345', 'Authorization': 'Basic MYAUTHSTRING=', 'x-customer-number': '123'
      • Using the wrong headers causes this error: "You do not have any exposures exempt at this time"
      • If you'd like to test if your token is valid, paste it in the Encoded section of this site. Payload Data should contain "customer_number" and "client_id"

The JavaScript tag facilitates communications between your website and CertCapture, and is typically added to your webpages by your company's web developer. Include this JavaScript tag on any application page that requires use of the CertCapture for eCommerce form.

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

Script examples for adding the token and JavaScript tags to your webpage are at the bottom of this article.

Configure initialization

Once you've added the Javascript tag to a page, activate the form with an initialization JavaScript either via a body.onload trigger or a manual trigger. If it's manually triggered, a custom body.onload function must be written to ensure that the script source is completely downloaded before an attempt is made to initialize or generate the form.

The GenCert.init function creates a new certificate generation form object tied to a parent DOM element supplied by <container>. This form is initially dormant until the show() function makes it visible. Specify the DOM object and JSON style parameter in the function, based on the example below.

GenCert.init(container, options)

  • Container - DOM object selected to be the form parent
  • Options - JSON style parameter object (option parameters below)

There are a number of options that you can use to provide pre, post, and callback functionality. A token and certificate zone must be provided for full functionality. This can be included in the constructor options or by specifically calling the setToken () and setShipZone () functions.

Syntax Description
token A JSON Web Token that claims security between CertCapture and your website for each ecommerce customer that wants to create an exemption document. You must access the CertCapture REST API to provide this token.
customer_number String identifying the customer number or unique identifier. This is not necessary if you are providing a token.
ship_zone String identifying exposure zones where a document is needed. Parameter must be a valid US or Canadian state or province with proper spacing, in any case. Ex: California or DISTRICT OF COLUMBIA.

 

Customize your script with functions

These callback functions will trigger automatically if defined:

Callback functions (triggered automatically if defined)
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
onManualSubmit Called when a Manual Submit zone/template is chosen
onNotNeeded Called when a Zone that does not charge sales tax is chosen
onUpload Called when a document is uploaded.  Access the generated certificate id with "GenCert.certificateIds"

These callback functions are common functions that should be overridden for custom website behavior:

Callback functions (Important Behaviors)
onCertSuccess This callback is usually overridden to perform a customized action such as user navigation after a certificate is successfully created
onCancel This callback should generally be used to reinitialize GenCert or provide user navigation
onManualSubmit This callback should generally be used to reinitialize GenCert or navigate the user elsewhere

These callback functions relate to customer data that can be populated in your form:

Customer data (Prefilled customer data - inner JSON object with string data fields)
customer
name
address1
address2
city
state
country
zip
phone
fax
email

These functions accept values of true or false, and allow greater customization of the form before, during, and after submission: 

Additional options and functions
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. Only supported when using a token.

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.

hide_sig

Signature not required for the document. The file is generated in CertCapture

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. 

Only supported when using a token.

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. Only supported when using a token.

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.

Example scripts

Simple Example Script Advanced Example Script

<html>
    <head>
           <script src="
https://app.certcapture.com/gencert2/js"></script>
    </head>
    <body>
        <div id="form_container"></div>
        <script>
            GenCert.init(document.getElementById("form_container"), {

                // The token and zone must set to start the process!!!

                token: ‘<token generated from your web application server>’,
                ship_zone: 'New York',
            });
            GenCert.show();
        </script>
    </body>
</html>

<html>
    <head>
        <script src="https://app.certcapture.com/gencert2/js"></script>
    </head>
    <body>
        <div id="form_container"></div>
        <script>
            GenCert.init(document.getElementById("form_container"), {
               

              // The token and zone must set to start the process!

                token: ‘<token generated from your web application server>’,

                onCertSuccess: function() {

                  alert('Certificate successfully generated with id:' + GenCert.certificateIds);

                  window.location = '/home';

                },

                onCancel: function() {

                  window.location = '/home';

                }
            });

 

            GenCert.setCustomerNumber('CustomerTestGencert4'); // create customer

            customer = new Object();

            customer.name = 'TEST NAME';

            customer.address1 = '1300 EAST CENTRAL';

            customer.city = 'San Francisco';

            customer.state = 'California';

            customer.country = 'United States';

            customer.phone = ‘555-555-5555’;

            customer.fax = ‘555-555-5555’;

            customer.zip = '89890';

            GenCert.setCustomerData(customer);

            GenCert.setShipZone('California');

            GenCert.show();
      </script>
    </body>
</html>

If you have any questions or concerns about the GenCert API, contact your Customer Account Manager (CAM) or Avalara Support.

  • Was this article helpful?