Guides

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.

Suggest Edits

🚧

This page is marked as deprecated, but Taxbit will continue supporting customers currently using these solutions. If you’d like to learn more about upgrading to our new React SDK with enhanced Digital W8/W9 support, reach out to our team today.

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.

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

Load the certify-only form as follows:

Loading the tax documentation form

taxBit.ui.taxDocumentation.certify({  
  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 critical events

The certify 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:

Receiving notification of events

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

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

await certifyResult.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.

sdk error message

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.

Handling errors

let certifyResult;

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

try {
  await certifyResult.formCompletion;
} catch (error) {
  // Handle the error that occurred 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.

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

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 W-9, W-8BEN, or W-8BEN-E. 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 fields required by the specified form type. An example of the W-9 form is the following:

taxBit.ui.taxDocumentation.certify({  
  hostElement: document.querySelector("#tax-info-container"),
  data: {
    documentType: "W-9",
    name: "Anthony Michael Pearson",
    address: {
      firstLine: "123 Lenny St.",
      city: "Seattle",
      stateOrProvince: "WA",
      postalCode: "98101",
      country: "US",
    },
    taxClassification: "INDIVIDUAL",
    tin: "123456432",
    tinType: "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 each individual form type:

W-9 documentType

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

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.

Note: This field is optional if a user has any of the following address.country or address.stateOrProvince: UM

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.

Note: This field is optional if a user has any of the following address.country or address.stateOrProvince: UM

address.stateOrProvince: string (required)

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.

Note: This field is optional if a user does not have any of the following address.country: PR, MP, GU, AS, VI, UM, US, or CA.

address.postalCode: string (required)

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

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

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will throw an error if:

  • You set the country to the US; this field doesn’t contain five or nine digits.
  • You set the country to CA; this field doesn’t contain six digits.

Note: This field is optional if a user does not have any of the following address.country or address.stateOrProvince: PR, MP, GU, AS, VI, UM, US, or CA.

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 valid ISO 3166-2 two-letter country code.

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

  • NN-NNNNNNN
  • NN-NNN-NNNN
  • NNNNNNNNN

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

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

tinType: string (optional)

This field contains the customer's TIN type.

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

dbaName: string (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 dbaName field.

taxClassification: string (required)

This field contains the customer's tax classification.

  • INDIVIDUAL
  • SOLE_PROPRIETOR
  • C_CORPORATION
  • S_CORPORATION
  • PARTNERSHIP
  • TRUST_ESTATE
  • LLC_C
  • LLC_S
  • LLC_P
  • OTHER

W-8BEN documentType

Note: Only fields that pertain to an individual W-8BEN form are supported.

name: string (required)

This field contains the legal name of the beneficial owner of the account. 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.

referenceNumbers: string (optional)

The legal name of the beneficial owner of the account.

taxClassification: string (required)

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

The supported value is:

  • INDIVIDUAL

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

country: string (required)

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

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

permanentAddress.firstLine: string (required)

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

The system will throw an error if you don't set the permanentAddress.country field or set it to an invalid country code.

Note: This field is optional if a user has any of the following permanentAddress.country or permanentAddress.stateOrProvince: UM

permanentAddress.secondLine: string (optional)

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

permanentAddress.city: string (required)

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

Note: This field is optional if a user has any of the following permanentAddress.country or permanentAddress.stateOrProvince: UM

permanentAddress.stateOrProvince: string (required)

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 permanent residence address. If the address is outside the U.S., this is a free-form string.

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

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

Note: This field is optional if a user does not have any of the following permanentAddress.country: PR, MP, GU, AS, VI, UM, US, or CA

permanentAddress.postalCode: string (required)

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

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

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will throw an error if

  • You set the country to the US, and this field is not five or nine digits long.
  • You set the country to CA; this field is not six digits long.

Note: This field is optional if a user does not have any of the following permanentAddress.country or permanentAddress.stateOrProvince: PR, MP, GU, AS, VI, UM, US, or CA

permanentAddress.country: string (required)

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

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.

mailingAddress: object (optional)

The customer’s mailing address. If the mailingAddress is provided, the subfields are as the following:

mailingAddress.firstLine: string (required)

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

The system will throw an error if you don't set the mailingAddress.country field or set it to an invalid country code.

Note: This field is optional if a user has any of the following mailingAddress.country or mailingAddress.stateOrProvince: UM

mailingAddress.secondLine: string (optional)

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

mailingAddress.city: string (required)

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

Note: This field is optional if a user has any of the following mailingAddress.country or mailingAddress.stateOrProvince: UM

mailingAddress.stateOrProvince: string (required)

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 mailing address. If the address is outside the U.S., this is a free-form string.

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

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

Note: This field is optional if a user does not have any of the following mailingAddress.country: PR, MP, GU, AS, VI, UM, US, or CA.

mailingAddress.postalCode: string (required)

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

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

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will throw an error if

  • You set the country to US, and this field is not five or nine digits long.
  • You set the country to CA, and this field is not six digits long.

Note: This field is optional if a user does not have any of the following mailingAddress.country or mailingAddress.stateOrProvince: PR, MP, GU, AS, VI, UM, US, or CA.

mailingAddress.country: string (required)

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

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.

dateOfBirth: string (required)

This key's value is the account owner's date of birth. It must be entered in the format MM/DD/YYYY.

tin: string (optional)

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

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

  • NN-NNNNNNN
  • NN-NNN-NNNN
  • NNNNNNNNN

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

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

ftin: string (required)

The value of this key is the customer's foreign tax identification number (FTIN).

ftinNotLegallyRequired: boolean (required)

The value of this key is whether the customer has indicated that they are legally not required to provide an FTIN.

W-8BEN-E documentType

name: string (required)

This field contains the legal name of the beneficial owner of the account. 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.

referenceNumbers: string (optional)

The legal name of the beneficial owner of the account.

taxClassification: string (required)

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

The supported values are:

  • CORPORATION
  • PARTNERSHIP
  • SIMPLE_TRUST
  • COMPLEX_TRUST
  • GRANTOR_TRUST
  • ESTATE
  • CENTRAL_BANK_OF_ISSUE
  • FOREIGN_GOVERNMENT_CONTROLLED_ENTITY
  • FOREIGN_GOVERNMENT_INTEGRAL_PART
  • TAX_EXEMPT_ORGANIZATION
  • PRIVATE_FOUNDATION
  • INTERNATIONAL_ORGANIZATION

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

country: string (required)

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

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

permanentAddress.firstLine: string (required)

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

The system will throw an error if you don't set the permanentAddress.country field or set it to an invalid country code.

Note: This field is optional if a user has any of the following permanentAddress.country or permanentAddress.stateOrProvince: UM

permanentAddress.secondLine: string (optional)

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

permanentAddress.city: string (required)

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

Note: This field is optional if a user has any of the following permanentAddress.country or permanentAddress.stateOrProvince: UM

permanentAddress.stateOrProvince: string (required)

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 permanent residence address. If the address is outside the U.S., this is a free-form string.

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

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

Note: This field is optional if a user does not have any of the following permanentAddress.country: PR, MP, GU, AS, VI, UM, US, or CA

permanentAddress.postalCode: string (required)

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

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

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will throw an error if

  • You set the country to US, and this field is not five or nine digits long.
  • You set the country to CA, and this field is not six digits long.

Note: This field is optional if a user does not have any of the following permanentAddress.country or permanentAddress.stateOrProvince: PR, MP, GU, AS, VI, UM, US, or CA

permanentAddress.country: string (required)

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

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.

mailingAddress: object (optional)

The customer’s mailing address. If the mailingAddress is provided, the subfields are as the following:

mailingAddress.firstLine: string (required)

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

The system will throw an error if you don't set the mailingAddress.country field or set it to an invalid country code.

Note: This field is optional if a user has any of the following mailingAddress.country or mailingAddress.stateOrProvince: UM

mailingAddress.secondLine: string (optional)

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

mailingAddress.city: string (required)

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

Note: This field is optional if a user has any of the following mailingAddress.country or mailingAddress.stateOrProvince: UM

mailingAddress.stateOrProvince: string (required)

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 mailing address. If the address is outside the U.S., this is a free-form string.

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

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

Note: This field is optional if a user does not have the following mailing.country: PR, MP, GU, AS, VI, UM, US, or CA.

mailingAddress.postalCode: string (required)

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

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

  • NNNNN
  • NNNNNNNNN
  • NNNNN-NNNN

The system will throw an error if:

  • You set the country to US, and this field is not five or nine digits long.
  • You set the country to CA, and this field is not six digits long.

Note: This field is optional if a user does not have any of the following mailingAddress.country or mailingAddress.stateOrProvince: PR, MP, GU, AS, VI, UM, US, or CA.

mailingAddress.country: string (required)

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

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.

tin: string (optional)

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

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

  • NN-NNNNNNN
  • NN-NNN-NNNN
  • NNNNNNNNN

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

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

ftin: string (required)

The value of this key is the customer's foreign tax identification number (FTIN).

ftinNotLegallyRequired: boolean (required)

The value of this key is whether the customer has indicated that they are legally not required to provide an FTIN.

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 certify 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.certify({  
  hostElement: document.querySelector("#tax-info-container"),
  data: {
    documentType: "W-9",
    name: "Anthony Michael Pearson",
    address: {
      firstLine: "123 Lenny St.",
      city: "Seattle",
      stateOrProvince: "WA",
      postalCode: "98101",
      country: "US,
    },
    taxClassification: "INDIVIDUAL",
    tin: "123456432",
    tinType: "SSN",
  },
  editUrl: "http://www.example.com/editUser/1"
});

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

Certify Screen

Updated about 1 month ago