Guides

React SDK (DAC7 Only) - v0.6

Suggest Edits

Getting Started

The TaxBit React SDK provides React components and hooks for gathering information from your end users to submit as tax documentation data to the TaxBit API to be used for DAC7 reporting. The SDK can be used with any React application to display a series of screens to your end users which are dynamic based on the information that the end user provides. This dynamic series of questions, coupled with extra data validation within the SDK as well as from the TaxBit platform, ensures that complete and correct information is collected.

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.

Installing the SDK

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

npm install @taxbit/react-sdk

Library Compatibility

The TaxBit React SDK is compatible with:

  • React versions: 16, 17, 18
  • TypeScript versions: 4, 5

Content Security Policy

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.

The TaxBit SDK will make requests to the TaxBit API. Your CSP must have the following entries for these requests to work.

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

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

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.

React Components

TaxBitDAC7Form

The TaxBitDAC7Form 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 { TaxBitDAC7Form } from '@taxbit/react-sdk';

<TaxBitDAC7Form
  data={exampleData}  // `data` is an optional prop
  bearerToken='bearer token goes here'
  language='en-us'  // 'en-us' is the default
  onProgress=(onProgressCallback}
  onSubmit={onSubmitCallback}
  onSuccess={onSuccessCallback}
/>

This component supports the following props:

  1. data - Used to provide pre-collected data.
  2. bearerToken - The token that the component will use to interact with the TaxBit API.
  3. language - Pre-selects the language to use in the form.
  4. 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.
  5. 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.
  6. onSuccess - A callback which is triggered once the TaxBit API has responded with a successful response that the data has been submitted.
  7. 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.
  8. onSettled - called after onError or onSuccess is called.

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 = {
  accountHolder: {
    name: "John Smith",
    tin: "456456456",
    ftin: "667788991",
    usAccountType: "individual",
    foreignAccountType: "individual",
    address: {
      firstLine: "123 Main St",
      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", // VAT number
    vatinCountry: "GR",  // VAT Countr
    vatinNotRequired: true,
    financialAccountIdentifier: "123123123",
    financialAccountName: "John Smith",
    isIndividual: true,
    isEuResident: true,
    isUsPerson: false,
  }
};

Editing Previous Data For Resubmission

The TaxBitDAC7Form component automatically fetches previously submitted data to pre-fill the form.

  • If the tax-documentation status of the account owner has a submission_status of SUBMITTED and a DAC7_interview.data_collection_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 the status has a submission_status of SUBMITTED and a DAC7_interview.data_collection_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 TaxBitDAC7Form 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 TaxBitDAC7Form 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 DAC7 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

Other Components

TaxBitDAC7FormUI

There is also a more basic TaxBitDAC7FormUI component which simply shows the form UI and returns the result in an onSubmit callback without interacting directly with the TaxBit API.

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

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

TaxBitForm

The TaxBitDAC7Form component is a wrapper around the TaxBitForm component. This component allows specifying the forms for which you want to collect information from the user. Only DAC7 is supported today. This will be extended in the future to support US tax forms such as W-9 and W-8 forms.

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

<TaxBitForm 
  data={exampleData}  // `data` is an optional prop
  bearerToken='bearer token goes here' 
  language='en-us'  //  also optional.  'en-us' is the default
  forms={['DAC7']}
  onProgress=(onProgressCallback}
  onSubmit={onSubmitCallback}
  onSuccess={onSuccessCallback}
/>

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' 
import { TaxBitDAC7Form } from '@taxbit/react-sdk';

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. 

bg-bg
cs-cz
da-dk
de-at
de-de
el-cy
el-gr
en-gb
en-us (default)
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

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.

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

const {
  status,
  submitForm
}: {
  postData: (data: ClientTaxDocumentation) => Promise<void>;
  serverData: ClientTaxDocumentation | undefined;
  status: ClientTaxDocumentationStatus | undefined;
} = useTaxBit(bearerToken);

Status

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

type ClientTaxDocumentationStatus = {
  submissionStatus: 'SUBMITTED' | 'NOT_SUBMITTED';
  DAC7Interview?: {
    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
    expirationDate: string;
    vatStatus: 'PENDING' | 'VALID' | 'INVALID' | 'NOT_REQUIRED';
    vatValidation_date: datetime;
  };
}
  • submissionStatus indicates if data has been submitted through the SDK for the requesting account owner.
  • DAC7Interview.dataCollectionStatus indicates if data that has been collected is considered complete for DAC7 reporting or not.
  • expirationDate is set to be three years after the date that the latest data for this account owner was submitted.

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

PostData

postData is a function which accepts the data that has been collected by the form and submits this data to the TaxBit API. This is the function the TaxbitDAC7Form component uses to submit the data to the TaxBit API.

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.

Changelog

Version 0.6.1

  1. Readme update

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.

Updated about 1 month ago