🚧

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.

Overview

IRS Form W-9, Form W-8BEN, Form W-8BEN-E

Companies use IRS Forms W-9 and W-8 to gather information from a person or entity they are paying. These IRS Forms classify people as US or Non-US Person.

• Form W-9: An IRS form that documents, under penalties of perjury, that an individual or entity is a US Person and collects the user’s Name and Tax Identification Number (TIN) for information reporting purposes (e.g., 1099 reporting).
• Form W-8BEN: An IRS form that documents, under penalties of perjury, that an individual is a Non-US Person 
• Form W-8BEN-E: An IRS form that documents, under penalties of perjury, that an entity is a Non-US Person.
• Substitute Form: A customizable form to collect user information that meets specific IRS criteria to be used interchangeably with an IRS Form W-9, W-8BEN, or W-8BEN-E.

Collecting Certified Taxpayer Identification Numbers (TINs) For U.S. Citizens

The Form W-9 documents a customer as a US Person and collects a certified TIN, where required. Using this form, a customer will provide their name, address, and a U.S. Social Security Number (SSN) or Employer Identification Number (EIN) based on their federal tax classification.

This guide will teach you to integrate TaxBit's SDK into your website to collect and certify the required account information and generate a Form W-9, W-8BEN, or W-8BEN-E document to meet the above requirements.

The high-level features include:

• Collecting and validating tax documentation data.
• Generating and downloading PDFs.
• Verifying U.S. Taxpayer Identification Numbers (TIN)
• Remediating tax documentation data.

Base URL

Your TaxBit Client Success Manager will provide you with the subdomain you will use to make your API calls to TaxBit. This guide uses the conventions:

• BASE_URL: This is the URL you will use to reference your production instance.
• BASE_SANDBOX: This is the URL you will use to reference your sandbox instance.

Authentication

For the TaxBit SDK to securely communicate with our TaxBit servers on your behalf, you must request a bearer token using information specific to your organization.

To request a bearer token, you'll need the following:

• Client ID
• Client Secret
• Tenant ID
• Account Owner ID
• Client Name (optional)

Your TaxBit representative will provide you with your Client Name, Client ID, Client Secret, and Tenant ID when you become a TaxBit customer.

Client Name is an optional parameter. Your Technical Consultant will confirm whether or not you need to populate this field.

WARNING: Your Client Secret is highly confidential. You must keep it safe where others cannot access it; otherwise, your account could be compromised.

Your Account Owner ID will be the ID of the account owner for whom you are collecting tax documentation. The Account Owner Scoped bearer token you are requesting will limit the scope of access so that only data for this account owner can be read or manipulated. In contrast, a Tenant Scoped bearer token will allow you to create account owners.

Requesting a bearer token

The SDK and TaxBit’s Digital Tax Documentation APIs require an Account Owner Scoped token. To request a bearer token, you must send a request to the Get an Account Owner Scoped Bearer Token endpoint in our TaxBit REST API. 

If you don’t have an account_owner_id yet, please get in touch with the TaxBit team to get started. 

Note: You should not make this request using code running in a web browser since doing so would expose your Client Secret, which must remain confidential.

Example

We will use Node.js in the example below to show you how to request a bearer token using code on your server via our Get an Account Owner Scoped Bearer Token endpoint.

Note: If you're using a version of Node.js older than 18.0.0, you'll need to install a third-party library, such as node-fetch, since older versions of Node.js don't include the features necessary to make a REST API request.

In the example below, you'll need to replace the placeholders, which begin with REPLACE_WITH, with the information specific to your account.

Requesting a bearer token

const response = await fetch(  
  "https://BASE_URL.taxbit.com/v1/oauth/account-owner-token",  
  {  
    method: "POST",  
    headers: {  
        "Content-Type": "application/x-www-form-urlencoded",  
    },  
    body: new URLSearchParams({  
        grant_type: "client_credentials",  
        client_id: "REPLACE_WITH_CLIENT_ID",  
        client_secret: "REPLACE_WITH_CLIENT_SECRET",  
        tenant_id: "REPLACE_WITH_TENANT_ID",  
        account_owner_id: "REPLACE_WITH_ACCOUNT_OWNER_ID",
    })
  }
);

const responseBody = await response.json();

console.log(responseBody.access_token);

Transferring the Bearer Token to Your Client Application Code

Once you've received your bearer token from the TaxBit REST API, you must send that token to your application code running in the browser. You will then pass the bearer token into the TaxBit SDK in a later step. The TaxBit SDK will use this bearer token to secure all your requests to the TaxBit servers.

Installing the SDK

We distribute the TaxBit SDK as an npm package through the public npm repository. As such, you may install the npm package using any npm-compatible package manager like npm, yarn, or pnpm.

Within your application's project directory, install the TaxBit SDK npm package as a dependency by executing the following in your terminal:

npm install @taxbit/browser

You can now import modules from the TaxBit SDK within your application code.

Instantiating the SDK

Import the @taxbit/browser package and instantiate the SDK. You will need to pass two pieces of information into the constructor:

• Client Name: Your TaxBit representative should have given you a Client Name when you first signed up. The Client Name must match the name you used to get your bearer token when you authenticated your application.
• Bearer Token: This is the token you received when you authenticated your application. You will use this token in all your requests to TaxBit's servers.

Using this example code will instantiate the TaxBit SDK. Please note you must replace the REPLACE_WITH_... placeholders with your information.

Instantiating the TaxBit SDK

import TaxBit from "@taxbit/browser";

const taxBit = new TaxBit({ 
  bearerToken: "REPLACE_WITH_BEARER_TOKEN",
});

You will use this authenticated instance of the TaxBit SDK in subsequent steps.

Using your sandbox environment

TaxBit provides both a production and sandbox environment for you when you sign up to be a TaxBit customer. You're encouraged to use fake data in the sandbox environment to test your implementation without polluting the production environment.

To use the sandbox environment, you must use your sandbox tenantId when retrieving a bearer token which is passed into the SDK. To use the production environment, use your production tenantId when retrieving a bearer token.

Note: TaxBit's new sandbox environments have replaced the previous staging environments that were provided to clients. If you are a client that is still using a staging environment, you must specify STAGING as the value for the environment parameter to the SDK.

import TaxBit from "@taxbit/browser";

const taxBit = new TaxBit({ 
  bearerToken: "REPLACE_WITH_BEARER_TOKEN",
  environment: "SANDBOX",
});

Note: The bearer tokens you use for your production and staging environments are unique. You cannot use a production bearer token to instantiate your TaxBit SDK on your staging environment.