Guides

React SDK (W9/W8/DPS) - v1.0 BETA

Suggest Edits

Getting Started

The Taxbit React SDK offers React components and hooks to collect and submit tax documentation, supporting W-9/W-8 forms and Digital Platform Seller (DPS) information collection. The DPS questionnaire enables compliance with Model Reporting Rules for Digital Platforms across multiple jurisdictions, including the EU (DAC-7), Canada, the UK, and New Zealand. The SDK integrates seamlessly with any React application to display a dynamic series of screens tailored to the information end users provide while ensuring accuracy through built-in data validation both in the SDK and via the Taxbit platform. This helps gather complete, compliant tax information from your end users.

📘

The React components also use structured and semantic HTML and CSS which can be easily customized using standard CSS to match your own application's own look and feel.

Prerequisites

You will need to complete the following steps to use the SDKt:

  1. Onboard with TaxBit as an API Customer. The implementation team will provide you with a clientId, clientSecret, and tenant details.
  2. Once you have received those credentials and your tenantId, get a tenant-scoped bearer token (see https://apidocs.taxbit.com/reference/post_oauth-token). The tenant-scoped bearer token is valid for 24 hours.
  3. Using your tenant-scoped bearer token, which the API returned to you in the previous request, create an Account Owner with associated PII (see https://apidocs.taxbit.com/reference/account-owners).
    1. You may also create an Account at the time of creating an Account Owner. Account IDs and Account Owner IDs can be the same if you don't have a distinction in your system (see https://apidocs.taxbit.com/reference/post_account-owners).
  4. Using your same tenant-scoped bearer token, create an Account using your Account Owner ID if you did not create an Account in step 3. Account IDs and Account Owner IDs can be the same if you don't have a distinction in your system (see https://apidocs.taxbit.com/reference/accounts).
  5. Retrieve an Account Owner bearer token to that will be used in the SDK (see https://apidocs.taxbit.com/reference/post_oauth-account-owner-token).

Installing the SDK

The Taxbit React SDK is available as a package through npm.

Beta Phase

During the beta phase, the SDK is fully supported, and can be used in production environments, however, there may be breaking changes without a new major version release. If used in a production environment, Taxbit recommends setting a fixed version, updating regularly, and testing after each update. This SDK provides early access to the latest functionality and allows for client feedback prior to general release.

npm i @taxbit/[email protected]

Library Compatibility

The Taxbit React SDK is compatible with:

  • React versions: 16, 17, 18
  • TypeScript versions: 4, 5
connect-src https://*.taxbit.com;

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

Your Taxbit representative will provide you with your 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.

The 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 API. 

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

📘

Note: This request cannot be made through a web browser and will be declined. Allowing browser-based code to make this request would expose your Client Secret, which must remain confidential. It must be made by the server.

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://api.multi1.enterprise.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);

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

React Component

When integrating with the SDK, you’ll render the TaxbitQuestionnaire component separately for type DPS or W-Form depending on which users you are gathering tax documentation information.

TaxbitQuestionnaire

The TaxbitQuestionnaire component can be imported from the @taxbit/react-sdk package and then rendered in your React application.

import '@taxbit/react-sdk/style/inline.css'; // other options include 'basic.css' and 'minimal.css'
import { TaxbitQuestionnaire, ClientTaxDocumentation } from '@taxbit/react-sdk';

<TaxbitQuestionnaire
  bearerToken="bearer token goes here"
  questionnaire="DPS"
  data={exampleData}
  language="en-us"
  onProgress=(onProgressCallback}
  onSubmit={onSubmitCallback}
  onSuccess={onSuccessCallback}
  loadingComponent={<div>Loading...</div>}
/>

This component supports the following props:

  1. data - Used to provide pre-collected data.
  2. bearerToken - (required) The token that the component will use to interact with the Taxbit API.
  3. questionnaire - (required) Specifies the type of questionnaire to show the user. Possible values are DPS and W-FORM.
  4. language - Pre-selects the language to use in the form.
  5. onProgress - A callback which is triggered when the user hits Next, Back, Cancel, or Submit buttons. A progress object is passed to the callback function.
  6. onSubmit - A callback which is triggered when the user hits the Submit button in the form. This callback happens before the POST request to the Taxbit API has returned to submit the data.
  7. onSuccess - A callback which is triggered once the Taxbit API has responded with a successful response that the data has been submitted.
  8. onError - called when the server responds with an error during data submission. The HTTP Response object from the fetch is passed to the error callback. If there is no onError callback, the response is thrown.
  9. onSettled - called after onError or onSuccess is called.
  10. loadingComponent - this component will be rendered instead of the default provided by the TaxbitQuestionnaire component.

onSubmit, onSuccess, and onSettled are each invoked with a parameter of type ClientTaxDocumentation which matches the type of the data prop.

Bearer Token

Retrieving a bearer token for use with the SDK is described above.

Providing Pre-collected Data

The data prop of the component allows passing in data that you already have in your application for all fields of the form.

exampleData: ClientTaxDocumentation = {
  accountHolder: {
    name: 'John Smith',
    tin: '456456456',
    ftin: '667788991',
    usAccountType: 'INDIVIDUAL',
    foreignAccountType: 'INDIVIDUAL',
    address: {
      firstLine: '123 Main St',
      secondLine: 'Unit #2',
      city: 'Seattle',
      stateOrProvince: 'WA',
      postalCode: '98000',
      country: 'GR',
    },
    mailingAddress: {
      firstLine: '123 Main St',
      city: 'Seattle',
      stateOrProvince: 'WA',
      postalCode: '98000',
      country: 'GR',
    },
    mailingAddressIsDifferent: true,
    countryOfCitizenship: 'GR',
    ftinNotLegallyRequired: true,
    taxResidences: [
      {
        country: 'GR',
        tin: '456456456',
        tinNotRequired: false,
      },
    ],
    vatin: '123123123',
    vatinCountry: 'GR',
    vatinNotRequired: true,
    financialAccountIdentifier: '123123123',
    financialAccountName: 'John Smith',
    businessRegistrationNumber: '123123123',
    businessRegistrationCountry: 'GR',
    isIndividual: true,
  },
};

Editing Previous Data For Resubmission

The TaxbitQuestionnaire component automatically fetches previously submitted data for the specified questionnaire type to pre-fill the form.

  • If data has been previously submitted and the data has a status of COMPLETE, the summary screen is immediately shown to the user, allowing them to view their previous data and edit the data to be resubmitted.
  • If data has been previously submitted but the data has a status of INCOMPLETE, the user will be taken through each screen of questions with the previous data prefilled, similar to the behavior of the data prop.
  • If the data prop is provided and there is already data that the account owner has submitted which the component fetches, the component will prefer data passed in directly through the data prop.

Callbacks

The Taxbit React SDK provides callbacks for the following events on the TaxbitQuestionnaire component. These callbacks can be passed in to the component and used to trigger other actions in your application.

  1. onSubmit - called when the user clicks the submit button. This function is passed the data TaxDocumentation object collected by the UI.
  2. onSuccess - called after the server responds with a successful submission. This function is passed the data TaxDocumentation object collected by the UI.
  3. onError - called when the server responds with an error during data submission.
  4. onSettled - called after onError or onSuccess is called.
  5. onProgress - called when the user navigates within the Taxbit UI. The function passed here will be passed a Progress object with the following shape:

Progress

The Progress object is available through the onProgress callback. This object provides information for how far the user has progressed through the form screens.

type Progress = {
  language: Locale;
  percentComplete: number;
  stepId: StepId;
  stepIndex: number;
  stepNumber: number;
  stepTitle: string;
  steps: StepId[];
  totalSteps: number;
};

The DPS sequence, for example, can have a total of 4, 5, or 6 steps, each with a localized stepTitle and stepId. The stepNumber is the current step (1 based), stepIndex is the currentStep (0 based), steps is the array of stepIds expected given the current state, and percentComplete is the percentage of the steps that have been completed.

Possible stepId values include:

accountHolderContactInformation
accountHolderTaxInformation
accountHolderTaxClarification
accountHolderClassification
confirmation
exemptions
regardedOwnerClassification
regardedOwnerContactInformation
regardedOwnerTaxInformation
summary

CSS and Style Customization

The Taxbit React SDK renders a form for collecting user data. The form is structured with semantic HTML and CSS classes and can be easily customized to closely match your application's style.

Built-in styling can be used by importing CSS files from the @taxbit/react-sdk package, but any CSS file can be provided which styles the same CSS class names. The inline.css file is a good example to reference for complete styling of the UI.

Each question and screen of the form has its own unique class name, namespaced to allow for styling customizations.

import '@taxbit/react-sdk/style/inline.css'; // other options include 'basic.css' and 'minimal.css'

Loading Component

When the TaxbitQuestionnaire component is fetching the status and tax documentation from the server, the TaxbitQuestionnaire component will display a text message my default "Retrieving interview status...". This can be customized by supplying a loadingComponent as a prop.

<TaxbitQuestionnaire
  bearerToken="bearer token goes here"
  questionnaire="W-FORM"
  loadingComponent={<div>Loading...</div>}
/>

Supported Languages

The following values are accepted for the language prop to localize the copy within each component. The end user can also control the language used directly with a dropdown shown in the UI, which can be hidden through CSS customization.

The DPS questionnaire is translated into all of these locales, the W-FORM questionnaire supports only en, es, and fr.

bg;      // Bulgarian
cs;      // Czech
da;      // Danish
de;      // German
de-at;   // German (Austria)
el;      // Greek
el-cy;   // Greek (Cyprus)
en;      // English
en-gb;   // English (United Kingdom)
en-nz;   // English (New Zealand)
en-us;   // English (United States)
es;      // Spanish
et;      // Estonian
fi;      // Finnish
fr;      // French
fr-ca;   // French (Canada)
fr-lu;   // French (Luxembourg)
ga;      // Irish
hr;      // Croatian
hu;      // Hungarian
it;      // Italian
lt;      // Lithuanian
lv;      // Latvian
mt;      // Maltese
nl;      // Dutch
nl-be;   // Dutch (Belgium)
no;      // Norwegian
pl;      // Polish
pt;      // Portuguese
ro;      // Romanian
sk;      // Slovak
sl;      // Slovenian
sv;      // Swedish

React Hooks

useTaxbit Hook

The useTaxbit hook is available to directly access the status of the account-owner’s tax documentation records and access functions for interacting with the Taxbit API. The hook also provides functions for determining if the customer has a PDF to download, and to get the url for download.

import { useTaxbit } from '@taxbit/react-sdk';

const {
  statusData,
  serverData,
  error,
  canGetDocumentUrl,
  generateDocumentUrl,
  isGeneratingDocumentUrl,
  documentUrl
}: {
  serverData: ClientTaxDocumentation | undefined;
  statusData: ClientTaxDocumentationStatus | undefined;
  error: Error;
  canGetDocumentUrl: boolean;
  generateDocumentUrl: () => void;
  isGeneratingDocumentUrl: boolean;
  documentUrl: string | undefined;
} = useTaxbit({ bearerToken, questionnaire, onError });

Status

The statusData object provides the data that is available from the tax-documentation-status API endpoint.

type ClientTaxDocumentationStatus = {
  dpsQuestionnaire?: {
    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
    vatStatus?:
      | 'PENDING'
      | 'VALID'
      | 'INVALID'
      | 'INSUFFICIENT_DATA'
      | 'NOT_REQUIRED'
      | 'NON_EU';
    vatValidationDate?: string;
    expirationDate?: string;
  };
  wFormQuestionnaire?: {
    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
    type: 'W-9' | 'W-8BEN' | 'W-8BEN-E';
    expirationDate?: string;
    tinStatus?:
      | 'PENDING'
      | 'FOREIGN'
      | 'INVALID_DATA'
      | 'VALID_SSN_MATCH'
      | 'VALID_EIN_MATCH'
      | 'VALID_SSN_EIN_MATCH'
      | 'MISMATCH'
      | 'TIN_NOT_ISSUED'
      | 'ERROR';
    tinValidationDate?: string;
    needsResubmission: boolean;
  };
};
  • If dpsQuestionnaire object is defined, this means that a DPS questionnaire has been previously submitted by the account-owner. If undefined, data has not yet been submitted. Likewise for wFormQuestionnaire and W-Form data.
  • dataCollectionStatus within dpsQuestionnaire and wFormQuestionnaire indicates if data that has been collected is considered complete for reporting or not.
  • dpsQuestionnaire.expirationDate is set to be three years after the date that the latest data for this account owner was submitted.
  • wFormQuestionnaire.needsResubmission indicates if the user should be instructed to submit new W-Form information. This can occur when a W-8 form has an issue that requires curing and a new submission from the end user.

VAT Validations

  • vatStatus indicates the status of the status of the VAT validation with the VIES VAT Number Validation system.
    • NOT_REQUIRED - The end user indicated that VAT is not required or has not been issued.
    • PENDING- The VAT value has yet to be validated with the VIES VAT Number Validation system.
    • VALID - The response from the VIES VAT Numver Validation tool is valid for the associated VAT number and country.
    • INVALID - The response from the VIES VAT Number Validation tool is invalid for the associated VAT number and country.
  • vatValidation_date indicates the date that the VAT value returned the present vat_status. If vatStatus is NOT_REQUIRED or PENDING, this value is NULL

TIN Validations

  • tinStatus indicates the status of a US TIN through verification with the IRS. Only TINs submitted for a W-9 are validated with the IRS.

ServerData

serverData is a ClientTaxDocumentation data saved on the server from the last customer session. This data is fetched and used to pre-populate the data in the UI.

useTaxbit hook error object

The useTaxbit hook also contains an error object which can be undefined, or an Error. If there is an error fetching or with the bearer token, the error property will be populated, and also logged to the console. If an onError callback is provided to the hook, the error will not be logged to the console.

PDF Document download

The useTaxbitHook gives access to four useful functions for generating a pdf document URL and allowing the user to download.

  • canGetDocumentUrl - this will be true if the customer submitted a valid W-9, W-8BEN, or W-8BEN-E
  • generateDocumentUrl - this will trigger the document URL generation. The URL is temporarily valid and expires in 5 minutes. It will be refreshed by the hook.
  • isGeneratingDocumentUrl - this will be true after the generateDocumentUrl request is made and before the document URL is available.
  • documentUrl - the temporary url for the document.
  const {
    canGetDocumentUrl,
    generateDocumentUrl,
    isGeneratingDocumentUrl,
    documentUrl,
  } = useTaxbit({ bearerToken, questionnaire });

Here is an example for how a separate Confirmation component could be used to render the button to download the pdf.


export const Confirmation = ({
  bearerToken,
  questionnaire,
}: {
  questionnaire: 'W-FORM' | 'DPS';
  bearerToken: string;
}) => {
  const {
    canGetDocumentUrl,
    generateDocumentUrl,
    isGeneratingDocumentUrl,
    documentUrl,
  } = useTaxbit({ bearerToken, questionnaire });

  useEffect(() => {
    if (canGetDocumentUrl) {
      generateDocumentUrl();
    }
  }, [canGetDocumentUrl]);

  const downloadButton = canGetDocumentUrl ? (
    documentUrl ? (
      <a href={documentUrl} className="taxbit-button" download>
        Download document
      </a>
    ) : isGeneratingDocumentUrl ? (
      <button className="taxbit-button" disabled>
        Generating PDF <InlineSpinner />
      </button>
    ) : null
  ) : null;

  return (
    <>
      <H2>Your tax form was created successfully!</H2>
      No further action is required.
      {downloadButton && (
        <>
          <p>You can download your tax form below for your records.</p>
          <p className="taxbit-primary-actions">{downloadButton}</p>
        </>
      )}
    </>
  );
};

To trigger the display of the Confirmation component, use the onSuccess callback handler in the TaxbitQuestionnaire component.

const ClientComponent = () => {  
  const [showConfirmation, setShowConfirmation] = useState(false);

  const onSuccess = () => {
    setShowConfirmation(true);
  };

  return showConfirmation ? (
    <Confirmation questionnaire="W-FORM" bearerToken={bearerToken} />
  ) : (
    <TaxbitQuestionnaire
      questionnaire="W-FORM"
      bearerToken={bearerToken}
      onSuccess={onSuccess}
    />
  );
};

Content Security Policy

The Taxbit SDK makes requests to the Taxbit API. If you have applied a content security policy (CSP) to your application, you may need to adjust your configuration for the Taxbit SDK to function correctly. Whether you need to make changes depends on the leniency of your CSP configuration.

Your CSP must have the following entries for these requests to work.

connect-src https://*.taxbit.com;

Updated 1 day ago