@taxbit/react-sdk v0.6.2

Taxbit React SDK

A React component and hook for gathering Tax Documentation data for US and EU Tax forms.

Usage

The Taxbit React SDK provides a React component, hook, and Typescript types for gathering tax documentation data from users. The component can be used to collect data for the Taxbit DPS (Digital Platform Sales) or W-Form (W-9, W-8BEN, W-8BEN-E) tax documentation forms. A hook provides more tools to understand the user's tax documentation status and download any pdf versions of the files that are created if eligible.

DPS (Digital Platform Sales) is a data standard and UI flow used by Taxbit to gather the information needed to report income as directed by the DAC7 for the European Union, and equivalent reporting requirements in Canada, New Zealand, and the United Kingdom.

Beta Stage

During this stage, the Taxbit 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.

Installation

npm install @taxbit/react-sdk

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

Data

const 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,
  },
};

The questionnaire prop determines the UI of the component. The questionnaire prop can be set to 'DPS' or 'W-FORM'.

<TaxbitQuestionnaire
  data={exampleData} // `data` is an optional prop
  bearerToken="bearer token goes here"
  questionnaire="DPS"
  language="en-us" // 'en-us' is the default
/>

For W-9, W-8BEN, and W-8BEN-E forms, the questionnaire prop is set like this...

<TaxbitQuestionnaire
  data={exampleData} // `data` is an optional prop
  bearerToken="bearer token goes here"
  questionnaire="W-FORM"
  language="en" // 'en' is the default
  treatyClaims={true} // 'treatyClaims' is an optional path for the W-8BEN and W-8BEN-E forms
/>

To view the Taxbit Questionnaire component without connecting to the server, you can put it in "demoMode". It can be used like this...

import { TaxbitQuestionnaire, ClientTaxDocumentation } from '@taxbit/react-sdk';

<TaxbitQuestionnaire
  data={exampleData}
  questionnaire="DPS"
  onSubmit={(data: ClientTaxDocumentation) => alert(JSON.stringify(data))}
  demoMode={true}
/>;

Bearer Token

This will be generated from the Taxbit API and passed in as a prop to the component.

Language

The first screen of the tax documentation interview gives the user the opportunity to select a language.
The language in the DPS component can be initially set to any of that languages that are supported by the Taxbit API.
The WForm component language can be set to 'en', 'fr', or 'es'.

See the Locale type below.

Treaty Claims

To collect treaty claims for the W-8BEN and W-8BEN-E forms, the treatyClaims prop can be set to true. This will add a screen to the W-8 flow where an eligible user can enter treaty claim specifics including the treaty country and rate of withholding.

useTaxbit Hook

The useTaxbit hook can be used to get the data from the server or the account status.

const {
  statusData,
  serverData,
  error,
  canGetDocumentUrl,
  generateDocumentUrl,
  isGeneratingDocumentUrl,
  documentUrl,
} = useTaxbit({ bearerToken, questionnaire, onError });

It can also be used to get the document URL for the user's tax documentation. The generateDocumentUrl function will trigger a temporary URL generation. The documentUrl will be the URL of the document if it is available. isGeneratingDocumentUrl will be true while the URL is being generated. canGetDocumentUrl will be true if the user has submitted the questionnaire and a PDF tax document is available to this user. Note, DPS data does not generate a PDF document.

Server Data

The serverData object contains the currently saved tax documentation data for the user. It is also a ClientTaxDocumentation object.

Status

The useTaxbit hook will return a status object that can be used to determine the status of the user's tax documentation. The status object will have the following shape:

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;
  };
};

an example is below.

{
  "dpsQuestionnaire": {
    "dataCollectionStatus": "COMPLETE",
    "expirationDate": "2026-11-20T00:00:00.000Z"
  }
}

or for W-Form status

{
  "wFormQuestionnaire": {
    "dataCollectionStatus": "COMPLETE",
    "type": "W-9",
    "tinValidationDate": "2027-11-01T17:09:05.962Z",
    "needsResubmission": false
  }
}

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.

CSS and Style Customization

The Taxbit React SDK renders a form for collecting user data. The form is structured with fairly semantic HTML and CSS classes and can be easily customized to closely match your client's style. Classnames are namespaced with "taxbit-" to reduce the chance of conflict.

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>}
/>

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.

• onSubmit - called when the user clicks the submit button. This can be an async function.
• onSuccess - called after the server responds with a successful submission.
• onError - called when the server responds with an error during data submission.
• onSettled - called after onError or onSuccess is called.
• onProgress - called when the user loads and navigates within the Taxbit UI. The function passed here will be passed a Progress object (see below for the type definition):

Error Boundary

A basic React Error Boundary is in place and when an error is thrown, the TaxbitQuestionnaire component will display errors on screen and throw an error in console. The exceptions that are possible are related to fetching data from the server, such as authentication (401 Unauthorized) or network problems (Failed to fetch). An error is also thrown if the bearer token is missing (Bearer Token is required). If the onError callback is provided to the component or the hook, these errors will be caught and passed to the callback. The error boundary will not be displayed.

The DPS sequence, for example, can have a total of 3, 4, or 5 steps, each with a localized stepTitle and stepId. The stepNumber is the current step (1 based), and percentComplete is the percentage of the steps that have been completed.

Types

The Taxbit React SDK provides a type for the status of the most recent tax documentation submitted by the user, referred to as ClientTaxDocumentationStatus. The data passed to the component and returned to the callback is typed as ClientTaxDocumentation.

Also included are some utility types:

type Locale =
  | 'bg'
  | 'cs'
  | 'da'
  | 'de'
  | 'de-at'
  | 'el'
  | 'el-cy'
  | 'en'
  | 'en-gb'
  | 'en-nz'
  | 'en-us'
  | 'es'
  | 'et'
  | 'fi'
  | 'fr'
  | 'fr-ca'
  | 'fr-lu'
  | 'ga'
  | 'hr'
  | 'hu'
  | 'it'
  | 'lt'
  | 'lv'
  | 'mt'
  | 'nl'
  | 'nl-be'
  | 'no'
  | 'pl'
  | 'pt'
  | 'ro'
  | 'sk'
  | 'sl'
  | 'sv';

type StepId =
  | 'accountHolderClassification'
  | 'accountHolderContactInformation'
  | 'accountHolderTaxInformation'
  | 'confirmation'
  | 'exemptions'
  | 'regardedOwnerClassification'
  | 'regardedOwnerContactInformation'
  | 'regardedOwnerTaxInformation'
  | 'summary';

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

type QuestionnaireType = 'DPS' | 'W-FORM';

Changelog

Version 1.1.0-beta.1

1. Small bug fixes related to mailing address and using enter key to submit.

Version 1.1.0-beta.0

1. Treaty Claims can now be collected for the W-8BEN and W-8BEN-E forms.

Version 1.0.0-beta.8

1. Signature confirmation is more flexible with spaces.
2. Fixed checkbox issue with certification upon submission.

Version 1.0.0-beta.7

1. BearerToken and Fetch errors are now sent only to the console, no longer thrown and bubbled up.
2. Added an error object to the 'useTaxbit' hook.

Version 1.0.0-beta.6

1. Bugs fixed related to the country drop-downs.
2. Added a loadingComponent prop to the TaxbitQuestionnaire component.

Version 1.0.0-beta.5

1. Document Generation modifications. Renamed from "getDocumentUrl" to "generateDocumentUrl".
2. onError callback is now exposed in both the TaxbitQuestionnaire component and the useTaxbit hook.

Version 1.0.0-beta.4

1. More explicit typing for TaxbitQuestionnaire component props

Version 1.0.0-beta.3

1. Transforming deprecated tax documentation data types for import to SDK
2. More Readme documentation around Status and Questionnaire types

Version 1.0.0-beta.2

1. The ClientTaxDocumentation type is exposed in the useTaxbit hook.

Version 1.0.0-beta.1

1. Showing "*" when required for Addresses on Summary

Version 1.0.0-beta.0

1. W-9, W-8BEN, and W-8BEN-E forms are now supported in the UI. The TaxbitQuestionnaire component can be used to collect data for these forms.
2. Translations for country names are now coming from the Intl API.
3. Download URL available in the useTaxbit hook.

Version 0.6.2

1. Added this Changelog file

Version 0.6.1

1. Native local terms for languages
2. Moved "Remove Residence" button, added section action button
3. Fixed Type for onSubmit callback. Callback can be async or not async.

Version 0.5.1

1. Place of Birth: Localized text update
2. Confirming valid ISO country code in data
3. Setting account holder name as the default value on Financial Account Identifier

Version 0.5.0

1. Adding all error messages to Summary Screen
2. Submit button is disabled when saved data matches local data
3. Indicate in form footer when errors are in the form above

Version 0.4.4

1. Handle blank bearer token. No error, but a warning is logged.

Version 0.4.3

1. Show error on VAT Identifier field when the Identifier is determined to be invalid
2. Fix: data should not reset on react render
3. Fix: changing data prop will reset form

Version 0.4.2

1. Added stepIndex and steps fields to the Progress object. stepId is now typed to potential enum values.

Version 0.4.1

1. Bug fix for onProgress callback not being triggered from the TaxBitDAC7Form component.

Version 0.4.0

1. Added onProgress callback.
2. Showing multiple errors for DAC7 Tax residency when the case arises.

Version 0.3.0

1. Added business registration questions to the form.
2. Added confirmation checkbox to the summary screen before submission.

Version 0.2.4

1. Bug fix for naming of CommonJS module exports.

Version 0.2.3

1. Bug fix for the ClientTaxDocumentationStatus type not being accessible externally.

Version 0.2.2

1. onSubmit and onSuccess callbacks are invoked with a parameter of type ClientTaxDocumentation which is now exposed.

Version 0.2.1

1. The SDK now supports React versions 16, 17, and 18 and TypeScript versions 4 and 5.

Version 0.2.0

1. Fix in package.json to expose UMD module as main.
2. Added specific CSS class names for each question and each screen of the form.
3. Added the new status structure into the useTaxbit hook.
4. TaxBitDAC7Form component will now preload the form with previously submitted data.
5. Validation update to enforce that primary address country and tax residence country are the same.