TaxBit React SDK

A React app, widget, and component for gathering Tax Documentation data for US and EU Tax forms.

Installation

npm install @taxbit/react-sdk

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

Data

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,
    isEuResident: true,
  },
};

<TaxBitDAC7Form
  data={exampleData} // `data` is an optional prop
  bearerToken="bearer token goes here"
  language="en-us" // 'en-us' is the default
  staging // if not production
/>

Which is just a shortcut for this component...

<TaxBitForm
  data={exampleData} // `data` is an optional prop
  bearerToken="bearer token goes here"
  language="en-us" // 'en-us' is the default
  forms={['DAC7']}
  staging // if not production
/>

There is a more basic component that simply shows the TaxBit UI and does not interact with the TaxBit server. It can be used like this...

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

<TaxBitDAC7FormUI
  data={exampleData}
  onSubmit={(data: ClientTaxDocumentation) => alert(JSON.stringify(data))}
/>;

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.
This can also be initially set to any of that languages that are supported by the TaxBit API.

See the Locale type below.

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:

{
  submissionStatus: 'SUBMITTED' | 'NOT_SUBMITTED';
  DAC7Interview: {
    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
    expirationDate: 'PENDING' |
      'VALID' |
      'INVALID' |
      'INSUFFICIENT_DATA' |
      'NOT_REQUIRED';
  }
}

an example is below.

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

Staging

This can be set to true or false. Passing staging in the component is the same as passing staging={true}.

If true, the staging environment will be used. If false, the production environment will be used. The default is false.

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 website's style. Classnames are namespaced with "taxbit-" to reduce the chance of conflict.

Callbacks

The TaxBit React SDK provides callbacks for the following events on the TaxBitDAC7Form 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):

The DAC7 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-bg'
  | 'cs-cz'
  | 'da-dk'
  | 'de-at'
  | 'de-de'
  | 'el-cy'
  | 'el-gr'
  | 'en-gb'
  | 'en-us'
  | 'es-es'
  | 'et-ee'
  | 'fi-fi'
  | 'fr-fr'
  | 'fr-lu'
  | 'ga-ie'
  | 'hr-hr'
  | 'hu-hu'
  | 'it-it'
  | 'lt-lt'
  | 'lv-lv'
  | 'mt-mt'
  | 'nl-be'
  | 'nl-nl'
  | 'no-no'
  | 'pl-pl'
  | 'pt-pt'
  | 'ro-ro'
  | 'sk-sk'
  | 'sl-si'
  | 'sv-se';

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

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

Changelog

Version 0.6.1

1. Moved Changelog file

Version 0.6.0

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.