[Archived - SDK v1.x]Certify-only Mode for Tax Documentation

Skip the Tax Documentation UI for collecting and editing data. Instead, your customer will jump to the final page in the UI for signing and certifying only.

A certify-only option is available in the TaxBit SDK, which allows you to submit all the tax documentation for your customer, exposing a single page for signing and certifying the data, where editing in the TaxBit UI is turned off.

Similar to the other options, when your customer submits this information, the system will send the data to TaxBit, where we will be safely store it and later use it to generate the necessary documents for tax compliance.

Load the certify-only form as follows:

taxBit.ui.taxDocumentation.loadCertifyForm({  
  hostElement: document.querySelector("#tax-info-container")
});

This code will create an iframe and append it to the DOM element specified in the hostElement option. The host element must be an element that can contain other elements. For example, users often use a div as the host element.

The iframe will then load and display a tax documentation collection form that TaxBit hosts on a Content Delivery Network (CDN). The iframe will occupy the entire width of the host element and will automatically resize its height to match the content inside the iframe. If you'd like to restrain the size of the tax collection form, set the height attribute and apply the overflow-y style on the host element to enable vertical scrolling.

Receiving notification of important events

The loadCertifyForm function will return a promise, which will resolve when the collection form has loaded into the iframe. The promise will resolve with an object containing another promise, which will resolve once the user submits the tax documentation form. For example:

const loadCertifyFormResult = await taxBit.ui.taxDocumentation.loadCertifyForm({  
  hostElement: document.querySelector("#tax-info-container")
});

// At this point, the form has been loaded in the iframe.

await loadCiertifyFormResult.formCompletion;

// At this point, the user has successfully completed the tax documentation form.

If errors occur while the form loads or while the user completes the form, the system will reject the promise. The SDK will do its best to display a friendly error message to the user; however, you should also handle these errors and provide a graceful user experience tailored to your application. For example, you could navigate the user to another part of your program.

let loadCertifyFormResult;

try {
  loadCertifyFormResult = await taxBit.ui.taxDocumentation.loadCertifyForm({  
    hostElement: document.querySelector("#tax-info-container")
  });
} catch (error) {
  // Handle the error that occured while loading the form.
}

try {
  await loadCertifyFormResult.formCompletion;
} catch (error) {
  // Handle the error that occured while the user was completing the form.
}

Specifying a document type

You can specify a document type, allowing the form to skip questions that would otherwise be necessary to determine the customer's target document type.

Note: The certify-only functionality can only generate W9 forms at this time. We don't currently support other values for documentType, but we plan to add support in a future release.

taxBit.ui.taxDocumentation.loadCertifyForm({  
  hostElement: document.querySelector("#tax-info-container"),
  documentType: "W9"
});

Providing pre-collected data

The certify-only feature is for you to use when you have all the information you need for your customer to sign and certify their W9. When you provide this data to the SDK, the SDK will validate your data's structure and content. Therefore, you must provide a data object that includes the data you have on your customer. This object must consist of the following fields:

taxBit.ui.taxDocumentation.loadCertifyForm({  
  hostElement: document.querySelector("#tax-info-container"),
  documentType: "W9"
  data: {
    name: "Anthony Michael Pearson",
    address: {
      firstLine: "123 Lenny St.",
      city: "Seattle",
      state: "WA",
      postalCode: "98101"
    },
    taxClassification: "INDIVIDUAL",
    taxId: "123456432",
    taxIdType: "SSN",
  }
});

The certify-only mode is strict, unlike the data validation for Collecting Tax Documentation, where the SDK intentionally provides leniency for provided values. Below are the data properties you must provide for an Individual W9:

Acceptable data for a documentType of W9

Note: Only fields that pertain to an individual W9 form are supported.

name: string (required)

This field contains the name of the account owner. You should not use this field for a Doing Business As (DBA) name. For individuals, this is the first and last name of the account owner (e.g., John Smith).

The system will throw an error if you don't set the taxClassification field to INDIVIDUAL.

address.firstLine: string (required)

This field contains the first line of the customer's address.
The system will throw an error if you don't set the address.country field or set it to an invalid country code.

address.secondLine: string (optional)

This field contains the second line of the customer's address.

address.city: string (required)

This field contains the city of the customer's address.

The system will throw an error if you don't set the address.city field.

address.stateOrProvince: string (required if 'US')

This field contains the state or province.

Note: If the address is within the US, you must set this field to the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is outside the US, you can set this to a free-form string or leave it undefined.

The system will throw an error if any of the following are true:

• Your set the address.country field to US (or the system derives US from the address.stateOrProvince field), but don't set this field to a valid ISO 3166-2 two-letter state code.
• You set the address.country field to an invalid country code

address.postalCode: string (required if 'US')

This field contains the postal code of the customer's address.

US Postal Codes can be in one of the following formats:

• #####
• #########
• #####-####

The system will throw an error if you set the country to US and this field is not five or nine digits long.

address.country: string (required)

This field contains the ISO 3166-2 two-letter country code for the country of the customer's address.

The system will throw an error if you don't provide a value in this field or if the value you provide is not a valid ISO 3166-2 two-letter country code.

taxId: string (required)

This field contains the Taxpayer Identification Number (TIN) of the customer.

The customer's TIN can be in one of the following formats:

• ##-#######
• ###-###-####
• #########

The system will throw an error if any of the following conditions are true:

• The taxId is not nine digits long.
• The taxId is fully ascending or descending, e.g., "123456789" or "987654321."
• The taxId is a single repeating digit, e.g., "111111111."

taxIdType: string (optional)

This field contains the customer's TIN type.

The system will throw an error unless the value you enter for taxIdType is SSN. The system will assume SSN if you leave this field blank.

nameLine2 (optional)

This field contains the owner's DBA name, trade name, or disregarded entity name.

Do not put the customer's name in this field. For example, if your customer's name is "Pat Smith" and their company's name is "Pat's Plumbing, LLC," You would put "Pat Smith" in the name field and "Pat's Plumbing, LLC" in the nameLine2 field.

taxClassification: string (required)

This field contains the customer's tax classification. You must set this field to INDIVIDUAL.

Adding a URL for your customers to edit their information

The certify-only feature hides the form for editing customer data in the TaxBit UI. If you want to direct your users to a page on your site to allow editing, you may add an editUrl to the loadCertifyForm options. To enable this feature, add any string to the editUrl field. The system will add an edit button to the top of the certify-only screen. Here's an example:

taxBit.ui.taxDocumentation.loadCertifyForm({  
  hostElement: document.querySelector("#tax-info-container"),
  documentType: "W9"
  data: {
    name: "Anthony Michael Pearson",
    address: {
      firstLine: "123 Lenny St.",
      city: "Seattle",
      state: "WA",
      postalCode: "98101"
    },
    taxClassification: "INDIVIDUAL",
    taxId: "123456432",
    taxIdType: "SSN",
  },
  editUrl: "http://www.example.com/editUser/1"
});

It will add a button to the top of the Certify screen.