Skip to main content
Avalara Help Center

Update your CertCapture for eCommerce Integration

Overview

You received email alerts about improvements to CertCapture for eCommerce released on June 14th, 2018 or received a pop-up alert in the CertCapture application reminding you to update. This article contains instructions for updating your ecommerce integration to use tokenization.

See Install CertCapture for eCommerce if this is your first time installing the integration.

Important Note: During this upgrade, remove "?cid=[value]&key=[value]" from the URL used in your JavaScript.

What happens to my ecommerce integration if I don't update it?

...by October 30th, 2018

The integration continues to work without an update, but certain functionality now requires an authorization token for increased security.

Customers using an ecommerce integration that hasn't been updated:

  • Can't view and complete a document with custom fields
  • Can't review or edit their customer information on repeated visits to your ecommerce platform
  • Can't view or download a PDF copy of the exemption document after it's been submitted to your ecommerce platform
  • Can't validate tax numbers when completing federal withholding forms

...by January 9, 2019

On January 9th, 2019, the CertCapture for eCommerce integration will require an authorized token to function. Any integration that has not been updated by this date will generate an error when attempting to load.

Update your CertCapture eCommerce integration

A website with CertCapture for eCommerce must now request 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 follow these steps.

You'll reference an API endpoint in our CertCapture REST API documentation.

  1. Sign into CertCapture and go to Settings > Company Settings > Company Details > eCommerce Settings, and then click Manage eCommerce Account.
    • Only a user with Admin permissions can access this setting
    • If this tab isn't present, an Admin must enable eCommerce in Settings > Account Settings > Features.
  2. Enter a username (Note: Usernames are case sensitive!), API password, and your CertCapture email address. Click Save
    • You'll use the username and API password again in Step 4
  3. Go to Settings > Company Settings > Company Details > Company Information and note the Company ID.
    • You'll also use the Company ID in Step 4
    • The API refers to the Company ID value as the client-id
  4. Generate a token using the username and password you just created, and the Company (client) ID. 
    • Tokens expire after one hour. Avalara recommends using a unique token per session
      • If a session lasts longer than sixty minutes, CertCapture refreshes the token to avoid interruptions
    • Token generation requires
      1. A customer number identifying the customer interacting with the ecommerce integration
      2. Your Company ID, which the API refers to as the client-id
    • 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 the error: "You do not have any exposures exempt at this time"
      • To test that your token is valid, paste it in the Encoded section of this site. Payload Data should contain "customer_number" and "client_id"
    • Use the drop-downs above the Header section on the right to view code examples in different languages, including Javascript, cURL, PHP, and more
    • The token code should be installed server side. 
  5. IMPORTANT: Remove "?cid=[value]&key=[value]" from the URL in your JavaScript. 
    • The new URL should be 
      "https://app.certcapture.com/gencert2/js
  6. The 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.
  7. Token values should be incorporated into the scripts on your front-end site. 

A JavaScript tag must be added to your webpage 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>

See Install CertCapture for eCommerce for incorporating your token, initializing your webform, and customizing your webform with functions.

 

Simple Script Example Advanced Script Example

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

  • Was this article helpful?