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), W-Form (W-9, W-8BEN, W-8BEN-E, W-8IMY), or Self-certification (DAC8, CARF) tax documentation forms. A hook provides additional tools to understand the user's tax documentation status and download any digital versions of the tax form files that are created if that are available.

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',
    accountOwnerType: '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,
    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
  dateFormat="mdy" // 'mdy' is the default
/>

For W-9, W-8BEN, W-8BEN-E, and W-8IMY form support, 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
  realTimeTinValidation={true} // 'realTimeTinValidation' is an optional prop for the W-9 form
/>

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.

Real-Time TIN Validation (also called "RTT")

If the realTimeTinValidation prop is set to true, the W-9 form will perform real-time TIN validation against the IRS database. This will provide immediate feedback to the user about the validity of their TIN. Note — the RTT feature must be turned on in the Taxbit API to successfully be used in the SDK.

Date Format

The date format can be set to mdy (month-day-year), dmy (day-month-year), or ymd (year-month-day). The default is mdy.

Adaptive Mode

Adaptive mode allows the questionnaire to intelligently skip steps and fields that already contain valid data, creating a more efficient user experience when updating or re-submitting tax documentation. The adaptiveMode prop accepts three values:

• 'full' (default): Normal behavior with no skipping. All steps and fields are shown regardless of existing data.
• 'skipEdit': Skip steps and fields that contain valid data, but allow users to edit them from the summary screen. This provides a streamlined experience while maintaining full editing capability.
• 'skipLock': Skip steps and fields that contain valid data and lock them from editing. Only fields with missing or invalid data will be shown.

<TaxbitQuestionnaire
  data={existingData}
  bearerToken="bearer token goes here"
  questionnaire="W-FORM"
  adaptiveMode="skipEdit" // or "skipLock" or "full"
/>

Adaptive mode is particularly useful when users are updating their tax documentation or when you have pre-filled data from previous submissions. The component will automatically skip entire steps if all required fields on that step are valid, and within steps, it will hide fields that already have valid values.

Region and Proxy Domain

The region prop can be set to either US or EU to determine which regional server the component will connect to. The default is US. The proxyDomain prop can be set to a custom domain to route requests through a proxy server. This is useful in environments where direct access to the Taxbit servers is restricted. If not provided, the component will connect directly to the Taxbit servers based on the selected region.

proxyHeaders are also allowed to be passed in as a prop to allow custom headers to be sent with each request when using a proxy server. They must be removed by the proxy server to avoid authorization issues with the Taxbit servers. authorization and content-type headers are reserved terms and used by the Taxbit server. If provided will be overwritten by the Taxbit values.

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,
  staging,
  region,
  proxyDomain,
  proxyHeaders,
  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 QuestionnaireIssue = {
  issueType:
    | 'CARE_OF_PERMANENT_ADDRESS'
    | 'PO_BOX_PERMANENT_ADDRESS'
    | 'US_PERMANENT_ADDRESS'
    | 'TREATY_COUNTRY_MISMATCH'
    | 'US_INDICIA'
    | 'WITHHOLDING_DOCUMENTATION'
    | 'CHANGE_IN_CIRCUMSTANCES';
  createdAt: string;
};

type ClientTaxDocumentationStatus = {
  dpsQuestionnaire?: {
    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
    expirationDate?: string;
    vatStatus?:
      | 'PENDING'
      | 'VALID'
      | 'INVALID'
      | 'INSUFFICIENT_DATA'
      | 'NOT_REQUIRED'
      | 'NON_EU';
    vatValidationDate?: string;
    needsResubmission?: boolean;
  };
  wFormQuestionnaire?: {
    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
    type: 'W-9' | 'W-8BEN' | 'W-8BEN-E' | 'W-8IMY';
    expirationDate?: string;
    issues?: QuestionnaireIssue[];
    needsResubmission?: boolean;
    tinStatus?:
      | 'PENDING'
      | 'FOREIGN'
      | 'INVALID_DATA'
      | 'VALID_SSN_MATCH'
      | 'VALID_EIN_MATCH'
      | 'VALID_SSN_EIN_MATCH'
      | 'MISMATCH'
      | 'TIN_NOT_ISSUED'
      | 'ERROR';
    tinValidationDate?: string;
    treatyClaimStatus?: 'VALID' | 'INVALID';
  };
  selfCertification?: {
    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
    issues?: QuestionnaireIssue[];
    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'
  | 'es-mx'
  | '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' | 'SELF-CERT';

Changelog

Version 3.6.0-beta.0

• needsResubmission: Added needsResubmission support for DPS and SELF-CERT questionnaires in ClientTaxDocumentationStatus.

Version 3.4.0-beta.0

• Powered by Taxbit: Optional Taxbit attribution in the component footer.
• Residencies: A component for capturing and validating data for tax residencies.

Version 3.3.1-beta.0

• Bug fix, clearing client-provided account holder data on a disregarded entity.

Version 3.3.0-beta.0

• Proxy Headers: New proxyHeaders prop allows passing custom HTTP headers through to all API requests, enabling support for proxy configurations and custom authentication schemes

Version 3.2.1-beta.0

• Bug fix, Fatca and Payee option text updated.

Version 3.2.0-beta.0

• CRS/CARF Self-Certification enhancements: Expand coverage to support both CARF and CRS within a single Self-Certification interview
• Translation enhancements: Expanded localized message properties and improved translation coverage across all supported languages.
• Tax residency confirmation: Added tax residency confirmation field.
• Signature capacity prefill: Automatically prefill signature capacity when provided.
• Controlling person improvements:
  • Display controlling person mailing address on summary screen.
  • Fixed validation report bugs for controlling person fields.
• Enhanced validation rules:
  • Added Australia (AU) and Great Britain (GB) country-specific validation rules.
  • Added Ivory Coast (CI) entity TIN validation regex patterns.

Version 3.1.0-beta.0

• Adaptive mode. Self-Certification support.
• Bug fix, white space only fields are not allowed if required.

Version 3.0.0-beta.1

• Bug fix, DOM on summary screen in adaptive mode had extraneous div.

Version 3.0.0-beta.0

• Adaptive mode. W-Form support

Version 2.5.0-beta.0

• New support for country-specific TIN and VAT warnings.
• New validations for New Zealand and Australia TIN values in DPS.
• Relax validation—VAT and TIN can be the same value.

Version 2.4.0-beta.0

• Adding region and proxyDomain props to the TaxbitQuestionnaire component for US, EU regional support and proxy domain support.

Version 2.3.0-beta.0

• Simplifying checkbox options on the Certification screen.

Version 2.2.0-beta.2

• Bug fix, hiding email field for non-AU residents.

Version 2.2.0-beta.1

• Updating TaxDocumentationStatus type to include issues and treatyClaimStatus.

Version 2.2.0-beta.0

• Adding SERR support for Australian residents.

Version 2.1.0-beta.0

• Adding Real-Time Tin Validation for W-9

Version 2.0.0-beta.2

• Adding es-MX ISO option.

Version 2.0.0-beta.1

• Fixed required fields for non-us Regarded Owner.

Version 2.0.0-beta.0

• W-8IMY support added.

Version 1.2.0-beta.8

1. Enforcing printable characters in the Foreign Tin
2. Adjusting treaty claims types of income.

Version 1.2.0-beta.7

• Verifying Mailing Address for W8-BEN-E, showing UsPerson selection on Summary screen.

Version 1.2.0-beta.6

• Fixing Treaty Claim header showing erroneously on the Summary screen.

Version 1.2.0-beta.4

• Passing investmentEntityManaged boolean to the server.

Version 1.2.0-beta.2

• React 17 issue fixed with void return types in components.

Version 1.2.0-beta.0

• Self-Certification support

Version 1.1.0-beta.1

1. Small bug fixes related to mailing address and using enter key to submit.
2. React 19 Support.

Version 1.1.0-beta.0

• Treaty Claims Support on W-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

• 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

• The ClientTaxDocumentation type is exposed in the useTaxbit hook.

Version 1.0.0-beta.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

• 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

• 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

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

Version 0.4.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

• Bug fix for naming of CommonJS module exports.

Version 0.2.3

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

Version 0.2.2

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

Version 0.2.1

• The SDK now supports React versions 16, 17, 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.