[Archived - SDK v1.x] Collecting Tax Documentation

You can use the tax form we provide in the TaxBit SDK to collect tax documentation from your customers. We will securely store this tax information on our servers and use it to generate the necessary documents for tax compliance.

You can load the collection form using the code sample below.

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

This will create an iframe and append it to the DOM element provided for the hostElement option. The host element must be an element that can contain other elements. A div is often provided as the host element.

The iframe will then load and display a tax documentation collection form which is hosted on a TaxBit content delivery network (CDN). The iframe will take the full 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 height of the tax collection form, set a height on the host element and apply the overflow-y style on the host element to enable vertical scrolling.

This code will create an iframe and append it to the DOM element you specified in the hostElement option. The host element must be able to contain nested elements. Typically, customers use a <div></div> block as the host element. Regardless of your HTML, we recommend giving your container element an attribute ID, like <div id="taxbit-container"></div>, making it easier to customize later.

The iframe will then display a form to collect tax documentation. We host this form on a TaxBit content delivery network (CDN). The iframe will use the entire width of the <div id="taxbit-container"></div> block and will automatically resize its height to match the content inside the iframe.

If you'd like to restrain the height of the tax collection form, You can use CSS to set the height of the <div id="taxbit-container"></div> block. You will also want to enable vertical scrolling. For example, <div id="taxbit-container" style="height: 3rem; overflow-y: scroll;"></div>. Otherwise, people may only see the top part of your form. See the documentation for overflow-y for more information.

Receiving notification of important events

The loadCreateForm function will return a promise, which the system will resolve once the collection form is fully loaded. We use an object to resolve this promise, which contains another promise that ve resolve once the user completes the tax documentation form successfully.

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

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

await loadCreateFormResult.formCompletion;

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

If errors occur while the form is loading or the user is working on it, the system will reject the abovementioned promises. The SDK will attempt 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.

let loadCreateFormResult;

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

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

Specifying a document type

By default, the collection form will ask your customer for information to determine whether they need a W8 or W9 tax form. However, if you know which document the customer qualifies for, you can pass that information into the form when you create it using the documentType key. Setting documentType will prevent the form from generating tax form related fields.

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

Supported document types

• UNDETERMINED<-- This is the default value if none is specified.
• W9

The W8 document type is not yet supported.

We currently don't support the W8 tax form, So if the system determines your customer needs a W8, they will see the following message. Therefore, if you know the customer needs a W8 form, please use the documentType key to specify UNDETERMINED, so the user won't see an error message.

We plan to provide W8 support soon.

⚠

️ The W8 document type is not yet supported

If you are unsure whether the user will need a W8 or W9, use the UNDETERMINED document type (the default). The SDK will ask questions to determine if a W8 is the appropriate document type for the account. If a W8 is the appropriate document type, the following message will be shown to the user.

We plan to provide W8 support in the near future.

Providing pre-collected data

Your system likely already has some basic information about your customer, like a name and address. By providing this data to the SDK, the SDK can auto-populate related form fields or skip questions altogether, resulting in a more streamlined experience for your customer. You can take advantage of this functionality by providing a data object that includes your existing data.

taxBit.ui.taxDocumentation.loadCreateForm({  
  hostElement: document.querySelector("#tax-info-container"),
  documentType: "W9"
  data: {
    name: "Anthony Michael Pearson",
    address: {
      firstLine: "123 Lenny St.",
      secondLine: "Apt 204",
      city: "Seattle",
      stateOrProvince: "WA",
      postalCode: "98101"
    },
    taxClassification: "INDIVIDUAL"
  }
});

The pieces of data you are allowed to provide depend on the value you have specified for documentType. For example, if documentType is UNDETERMINED, you may only provide data that is common between W8 and W9 forms.

Note: The SDK intentionally provides leniency for provided values. For example, if you pass an invalid value of foo for taxClassification, the SDK will discard the value rather than throw an error. The collection form will then ask your customer whatever questions are necessary to arrive at accurate and complete data. Rules for when field values will be discarded are detailed below.

Acceptable data for a documentType of UNDETERMINED

We only support fields that both the W8 and W9 forms share.

name: string (optional)

For individuals, the value of this key is the first and last name of the account owner, not the name of their company—for example, Phil Myman.

For businesses, this is the name of the business that owns the account—for example, Company ABC Inc.

The system will discard this value if you set the taxClassification field to SMLLC.

address.firstLine: string (optional)

The value of this key is the first line of the customer's address.

The system will discard this field if any of the following conditions are true:

• The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
• You've set the taxClassification field to SMLLC.

address.secondLine: string (optional)

The value of this key is the second line of the customer's address.

This system will discard this field if any of the following conditions are true:

• The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
• You've set the taxClassification field to SMLLC.

address.city: string (optional)

The value of this key is the customer's city.

The system will discard this field if any of the following conditions are true:

• The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
• You've set the taxClassification field to SMLLC.

address.stateOrProvince: string (optional)

If the address is within the U.S., this must be the ISO 3166-2 two-letter state code of the state of the customer's address. If the address is outside the U.S., this is a free-form string.

The system will discard this field if any of the following conditions are true:

• The ISO 3166-2 two-letter state code is invalid. For example, if you set the address.country to ZZ, the system would discard this field.
• The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
• You've set the taxClassification field to SMLLC.

address.postalCode: string (optional)

The value of this key is the postal code of the customer's address.

U.S. Postal Codes can be in one of the following formats:

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

The system will discard this field if any of the following conditions are true:

• If the address is within the U.S., but the postal code is not a five or nine-digit string.
• The address.country field is empty, invalid, or the system cannot derive it from address.stateOrProvince.
• You've set the taxClassification field to SMLLC.

Note: If the system discards this field, it will ask the customer to enter a valid postal code.

address.country: string (optional)

The value of this key is the ISO 3166-2 two-letter country code for the customer's country.

The system will discard this field if any of the following conditions are true:

• The ISO 3166-2 two-letter country code is empty, invalid, or the system cannot derived it from address.stateOrProvince.
• You've set the taxClassification field to SMLLC.

Note: If you don't provide a value for this field, the system will try to derive the country code using address.stateOrProvince.

taxId: string (optional)

The value of this key is the customer's Taxpayer Identification Number (TIN).

The Taxpayer ID Number (TIN) can be in one of the following formats:

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

The system will discard this field if any of the following conditions are true:

• The value is not a nine-digit string.
• The taxIdType field is empty.
• You've set the taxClassification field to SMLLC.

taxIdType: string (optional)

The value of this key is the customer's TIN type.

Supported values:

• SSN
• EIN

The system will discard this field if any of the following conditions are true:

• The value is not supported.
• You have already entered a valid value in the taxClassification field. In this case, the system will automatically set the value of taxIdType to the appropriate Tax ID type.
• You've set the taxClassification field to SMLLC.

Acceptable data for documentType of W9

We support all properties listed for UNDETERMINED and the following W9-specific properties.

nameLine2 (optional)

The value of this field is the Doing Business As (DBA) name, trade name, or the disregarded entity name of the account owner. It is different from the name property listed above. For example, the name field might be Pat Smith, whereas nameLine2 might be Pat's Plumbing LLC.

The system will discard this field if you've set the taxClassification field to SMLLC.

taxClassification: string (optional)

The value of this key is the tax classification of the customer.

The supported values are:

• INDIVIDUAL
• SOLE_PROPRIETOR
• SMLLC
• C_CORPORATION
• S_CORPORATION
• PARTNERSHIP
• TRUST_ESTATE
• LLC
• OTHER

The system will discard this field if its value isn't one of the enumerated values above.

llcTaxClassification: string (optional)

The value of this key is the optional tax classification of an LLC that wants to be treated as an entity and has made an 8832 or 2553 election.

Supported values:

• C_CORPORATION
• S_CORPORATION
• PARTNERSHIP

The system will discard this field if any of the following conditions are true:

• The value is different from the enumerated values above.
• You've set the taxClassification field to SMLLC.

otherTaxClassification: string (optional)

If the customer falls into an other tax classification, provide the tax classification of that entity. Any string is acceptable.

The system will discard this field unless you set the taxClassification field to OTHER.

exemptPayeeCode:string (optional)

The exempt payee code applies to specific types of businesses and government entities generally exempt from backup withholding and information reporting requirements. These exempt codes generally do not apply to individuals.

There are thirteen codes, with values from 1 to 13, with each number representing a qualifying entity type. For example, payee code 7 means a futures commission merchant registered with the Commodity Futures Trading Commission. You can find all the exempt payee codes in the instructions on Form W-9.

The system will discard this field if any of the following conditions are true:

• The value is not a string representation of any number between 1 and 13.
• You've set the taxClassification field to SMLLC.

exemptionFatcaCode:string (optional)

The Foreign Account Tax Compliance Act (FATCA) reporting exempt code is similar to the exempt payee code but relates to those businesses and government entities exempt from FATCA reporting. FATCA is a global tax regime directed at U.S. tax residents who maintain accounts with foreign financial institutions. These exempt codes generally do not apply to individuals.

There are thirteen codes, with values of A to M, with each letter representing a qualifying entity type. For example, FATCA exempt code D means a corporation whose stock is regularly traded on one or more established securities markets as described in Regulations section 1.1472-1(c)(1)(i). You can find all the exempt payee codes in the instructions on Form W-9.

The system will discard this field if any of the following conditions are true:

• The value is not a character between A and M.
• You've set the taxClassification field to SMLLC.