React SDK (W9/W8/DPS) - v1.0 BETA
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:
- Onboard with TaxBit as an API Customer. The implementation team will provide you with a
clientId
,clientSecret
, and tenant details. - 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. - 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).
- 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).
- 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).
- 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:
data
- Used to provide pre-collected data.bearerToken
- (required) The token that the component will use to interact with the Taxbit API.questionnaire
- (required) Specifies the type of questionnaire to show the user. Possible values areDPS
andW-FORM
.language
- Pre-selects the language to use in the form.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.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.onSuccess
- A callback which is triggered once the Taxbit API has responded with a successful response that the data has been submitted.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.onSettled
- called afteronError
oronSuccess
is called.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 thedata
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 thedata
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.
onSubmit
- called when the user clicks the submit button. This function is passed the data TaxDocumentation object collected by the UI.onSuccess
- called after the server responds with a successful submission. This function is passed the data TaxDocumentation object collected by the UI.onError
- called when the server responds with an error during data submission.onSettled
- called afteronError
oronSuccess
is called.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,
canGetDocumentUrl,
generateDocumentUrl,
isGeneratingDocumentUrl,
documentUrl
}: {
serverData: ClientTaxDocumentation | undefined;
statusData: ClientTaxDocumentationStatus | undefined;
canGetDocumentUrl: boolean;
generateDocumentUrl: () => void;
isGeneratingDocumentUrl: boolean;
documentUrl: string | undefined;
} = useTaxbit({ bearerToken, questionnaire });
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 forwFormQuestionnaire
and W-Form data. dataCollectionStatus
withindpsQuestionnaire
andwFormQuestionnaire
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 presentvat_status
. IfvatStatus
isNOT_REQUIRED
orPENDING,
this value isNULL
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.
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 2 days ago