@taxbit/react-sdk 2.0.0-beta.2 → 2.1.0-beta.0

package/README.md

@@ -91,10 +91,11 @@ For W-9, W-8BEN, W-8BEN-E, and W-8IMY form support, the `questionnaire` prop is
   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...
+To view the Taxbit Questionnaire component without connecting to the server, you can put it in `demoMode`. It can be used like this...
 
 ```typescript jsx
 import { TaxbitQuestionnaire, ClientTaxDocumentation } from '@taxbit/react-sdk';
@@ -123,6 +124,10 @@ See the `Locale` type below.
 
 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`.
@@ -328,6 +333,10 @@ type QuestionnaireType = 'DPS' | 'W-FORM' | 'SELF-CERT';
 
 ## Changelog
 
+### Version 2.1.0-beta.0
+
+1. Adding Real-Time Tin Validation for W-9
+
 ### Version 2.0.0-beta.2
 
 1. Adding es-MX ISO option.

package/dist/src/components/Row/Row.d.ts

@@ -4,10 +4,11 @@ import { TaxDocumentationKey } from 'types/TaxDocumentation';
 export type RowProps = {
     label?: string;
     subLabel?: string;
+    badge?: boolean;
     value?: string;
     onEdit?: () => void;
     children?: React.ReactNode;
     className?: string;
-    name?: TaxDocumentationKey;
+    name: TaxDocumentationKey;
 };
-export declare const Row: ({ label, subLabel, value, children, onEdit, name, className, }: RowProps) => React.JSX.Element;
+export declare const Row: ({ badge, label, subLabel, value, children, onEdit, name, className, }: RowProps) => React.JSX.Element;

package/dist/src/contexts/QuestionnaireStep/getLocal.d.ts

@@ -1,21 +1,24 @@
+import { UsTinValidationAttempt, UsTinValidationStatus } from 'hooks';
 import { ButtonKey, ErrorKey, PromptKey, SubPromptKey, SubTitleKey, TextKey } from '../../i18n/types';
 import { Locale, QuestionnaireProp, TaxDocumentation, TaxDocumentationKey } from '../../types';
 
-export declare const getLocal: (fields: TaxDocumentation, language: Locale, questionnaire: QuestionnaireProp) => {
-    getLocalText: (key: TextKey) => string;
-    getLocalTitle: (key: string) => string;
-    getLocalSubTitle: (key: SubTitleKey) => string;
-    getLocalError: (key: ErrorKey) => string;
+export declare const getLocal: (fields: TaxDocumentation, language: Locale, questionnaire: QuestionnaireProp, usTinValidations?: UsTinValidationAttempt[]) => {
+    getBadgeKey: (key: TaxDocumentationKey) => UsTinValidationStatus | undefined;
+    getLocalAddressTitle: (data: TaxDocumentation) => string;
+    getLocalBadge: (key: TaxDocumentationKey) => string | undefined;
     getLocalButton: (key: ButtonKey) => string;
-    getLocalPrompt: (key: string) => string;
-    getLocalSubPrompt: (key: TaxDocumentationKey) => string;
+    getLocalCaProvince: (key: string | undefined) => string;
+    getLocalCountry: (key: string | undefined) => string;
+    getLocalError: (key: ErrorKey) => string;
+    getLocalMonth: (key: string | undefined) => string;
     getLocalOption: (key: string | undefined, prefix?: string) => string | undefined;
+    getLocalPrompt: (key: string) => string;
     getLocalSubOption: (key: string | undefined) => string | undefined;
-    getLocalCountry: (key: string | undefined) => string;
+    getLocalSubPrompt: (key: TaxDocumentationKey) => string;
+    getLocalSubTitle: (key: SubTitleKey) => string;
+    getLocalText: (key: TextKey) => string;
+    getLocalTitle: (key: string) => string;
     getLocalUsState: (key: string | undefined) => "" | "Alabama" | "Alaska" | "Arizona" | "Arkansas" | "California" | "Colorado" | "Connecticut" | "Delaware" | "District Of Columbia" | "Florida" | "Georgia" | "Hawaii" | "Idaho" | "Illinois" | "Indiana" | "Iowa" | "Kansas" | "Kentucky" | "Louisiana" | "Maine" | "Maryland" | "Massachusetts" | "Michigan" | "Minnesota" | "Mississippi" | "Missouri" | "Montana" | "Nebraska" | "Nevada" | "New Hampshire" | "New Jersey" | "New Mexico" | "New York" | "North Carolina" | "North Dakota" | "Ohio" | "Oklahoma" | "Oregon" | "Pennsylvania" | "Rhode Island" | "South Carolina" | "South Dakota" | "Tennessee" | "Texas" | "Utah" | "Vermont" | "Virginia" | "Washington" | "West Virginia" | "Wisconsin" | "Wyoming";
-    getLocalCaProvince: (key: string | undefined) => string;
-    getLocalMonth: (key: string | undefined) => string;
-    getLocalAddressTitle: (data: TaxDocumentation) => string;
     getPromptKey: (key: string) => PromptKey;
     getSubPromptKey: (key: string) => SubPromptKey;
 };

package/dist/src/contexts/QuestionnaireStep/useQuestionnaireStep.d.ts

@@ -9,20 +9,22 @@ export type TaxDocumentationErrorFile = {
     [key in TaxDocumentationKey]?: ErrorKey[];
 };
 export declare const useQuestionnaireStep: () => {
-    getLocalText: (key: import('i18n/types').TextKey) => string;
-    getLocalTitle: (key: string) => string;
-    getLocalSubTitle: (key: import('i18n/types').SubTitleKey) => string;
-    getLocalError: (key: ErrorKey) => string;
+    getBadgeKey: (key: TaxDocumentationKey) => import('../../hooks').UsTinValidationStatus | undefined;
+    getLocalAddressTitle: (data: TaxDocumentation) => string;
+    getLocalBadge: (key: TaxDocumentationKey) => string | undefined;
     getLocalButton: (key: import('i18n/types').ButtonKey) => string;
-    getLocalPrompt: (key: string) => string;
-    getLocalSubPrompt: (key: TaxDocumentationKey) => string;
+    getLocalCaProvince: (key: string | undefined) => string;
+    getLocalCountry: (key: string | undefined) => string;
+    getLocalError: (key: ErrorKey) => string;
+    getLocalMonth: (key: string | undefined) => string;
     getLocalOption: (key: string | undefined, prefix?: string) => string | undefined;
+    getLocalPrompt: (key: string) => string;
     getLocalSubOption: (key: string | undefined) => string | undefined;
-    getLocalCountry: (key: string | undefined) => string;
+    getLocalSubPrompt: (key: TaxDocumentationKey) => string;
+    getLocalSubTitle: (key: import('i18n/types').SubTitleKey) => string;
+    getLocalText: (key: import('i18n/types').TextKey) => string;
+    getLocalTitle: (key: string) => string;
     getLocalUsState: (key: string | undefined) => "" | "Alabama" | "Alaska" | "Arizona" | "Arkansas" | "California" | "Colorado" | "Connecticut" | "Delaware" | "District Of Columbia" | "Florida" | "Georgia" | "Hawaii" | "Idaho" | "Illinois" | "Indiana" | "Iowa" | "Kansas" | "Kentucky" | "Louisiana" | "Maine" | "Maryland" | "Massachusetts" | "Michigan" | "Minnesota" | "Mississippi" | "Missouri" | "Montana" | "Nebraska" | "Nevada" | "New Hampshire" | "New Jersey" | "New Mexico" | "New York" | "North Carolina" | "North Dakota" | "Ohio" | "Oklahoma" | "Oregon" | "Pennsylvania" | "Rhode Island" | "South Carolina" | "South Dakota" | "Tennessee" | "Texas" | "Utah" | "Vermont" | "Virginia" | "Washington" | "West Virginia" | "Wisconsin" | "Wyoming";
-    getLocalCaProvince: (key: string | undefined) => string;
-    getLocalMonth: (key: string | undefined) => string;
-    getLocalAddressTitle: (data: TaxDocumentation) => string;
     getPromptKey: (key: string) => import('i18n/types').PromptKey;
     getSubPromptKey: (key: string) => import('i18n/types').SubPromptKey;
     clearIfNotRequired: (...arg: TaxDocumentationKey[]) => (value: Yes | undefined) => void;
@@ -41,4 +43,8 @@ export declare const useQuestionnaireStep: () => {
     hideField: (key: TaxDocumentationKey) => void;
     showField: (key: TaxDocumentationKey) => void;
     dateFormat: import('../TaxDocumentation/useTaxDocumentation').DateFormatConfig;
+    doVerify: () => Promise<void>;
+    isVerifying: boolean;
+    isDoneVerifying: boolean;
+    usTinValidations: import('../../hooks').UsTinValidationAttempt[];
 };

package/dist/src/contexts/QuestionnaireStep/useQuestionnaireStepContext.d.ts

@@ -1,18 +1,20 @@
 export declare const useQuestionnaireStepContext: () => {
-    getLocalText: (key: import('../../i18n/types/LocalizationKey.ts').TextKey) => string;
-    getLocalTitle: (key: string) => string;
-    getLocalSubTitle: (key: import('../../i18n/types/LocalizationKey.ts').SubTitleKey) => string;
-    getLocalError: (key: import('../../i18n/types/LocalizationKey.ts').ErrorKey) => string;
+    getBadgeKey: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => import('../../hooks/index.ts').UsTinValidationStatus | undefined;
+    getLocalAddressTitle: (data: import('../../types/TaxDocumentation.ts').TaxDocumentation) => string;
+    getLocalBadge: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => string | undefined;
     getLocalButton: (key: import('../../i18n/types/LocalizationKey.ts').ButtonKey) => string;
-    getLocalPrompt: (key: string) => string;
-    getLocalSubPrompt: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => string;
+    getLocalCaProvince: (key: string | undefined) => string;
+    getLocalCountry: (key: string | undefined) => string;
+    getLocalError: (key: import('../../i18n/types/LocalizationKey.ts').ErrorKey) => string;
+    getLocalMonth: (key: string | undefined) => string;
     getLocalOption: (key: string | undefined, prefix?: string) => string | undefined;
+    getLocalPrompt: (key: string) => string;
     getLocalSubOption: (key: string | undefined) => string | undefined;
-    getLocalCountry: (key: string | undefined) => string;
+    getLocalSubPrompt: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => string;
+    getLocalSubTitle: (key: import('../../i18n/types/LocalizationKey.ts').SubTitleKey) => string;
+    getLocalText: (key: import('../../i18n/types/LocalizationKey.ts').TextKey) => string;
+    getLocalTitle: (key: string) => string;
     getLocalUsState: (key: string | undefined) => "" | "Alabama" | "Alaska" | "Arizona" | "Arkansas" | "California" | "Colorado" | "Connecticut" | "Delaware" | "District Of Columbia" | "Florida" | "Georgia" | "Hawaii" | "Idaho" | "Illinois" | "Indiana" | "Iowa" | "Kansas" | "Kentucky" | "Louisiana" | "Maine" | "Maryland" | "Massachusetts" | "Michigan" | "Minnesota" | "Mississippi" | "Missouri" | "Montana" | "Nebraska" | "Nevada" | "New Hampshire" | "New Jersey" | "New Mexico" | "New York" | "North Carolina" | "North Dakota" | "Ohio" | "Oklahoma" | "Oregon" | "Pennsylvania" | "Rhode Island" | "South Carolina" | "South Dakota" | "Tennessee" | "Texas" | "Utah" | "Vermont" | "Virginia" | "Washington" | "West Virginia" | "Wisconsin" | "Wyoming";
-    getLocalCaProvince: (key: string | undefined) => string;
-    getLocalMonth: (key: string | undefined) => string;
-    getLocalAddressTitle: (data: import('../../types/TaxDocumentation.ts').TaxDocumentation) => string;
     getPromptKey: (key: string) => import('../../i18n/types/LocalizationKey.ts').PromptKey;
     getSubPromptKey: (key: string) => import('../../i18n/types/LocalizationKey.ts').SubPromptKey;
     clearIfNotRequired: (...arg: import('../../types/TaxDocumentation.ts').TaxDocumentationKey[]) => (value: import('../../types/Yes.ts').Yes | undefined) => void;
@@ -31,21 +33,27 @@ export declare const useQuestionnaireStepContext: () => {
     hideField: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => void;
     showField: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => void;
     dateFormat: import('../TaxDocumentation/useTaxDocumentation.ts').DateFormatConfig;
+    doVerify: () => Promise<void>;
+    isVerifying: boolean;
+    isDoneVerifying: boolean;
+    usTinValidations: import('../../hooks/index.ts').UsTinValidationAttempt[];
 }, QuestionnaireStepContextProvider: import('react').Provider<{
-    getLocalText: (key: import('../../i18n/types/LocalizationKey.ts').TextKey) => string;
-    getLocalTitle: (key: string) => string;
-    getLocalSubTitle: (key: import('../../i18n/types/LocalizationKey.ts').SubTitleKey) => string;
-    getLocalError: (key: import('../../i18n/types/LocalizationKey.ts').ErrorKey) => string;
+    getBadgeKey: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => import('../../hooks/index.ts').UsTinValidationStatus | undefined;
+    getLocalAddressTitle: (data: import('../../types/TaxDocumentation.ts').TaxDocumentation) => string;
+    getLocalBadge: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => string | undefined;
     getLocalButton: (key: import('../../i18n/types/LocalizationKey.ts').ButtonKey) => string;
-    getLocalPrompt: (key: string) => string;
-    getLocalSubPrompt: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => string;
+    getLocalCaProvince: (key: string | undefined) => string;
+    getLocalCountry: (key: string | undefined) => string;
+    getLocalError: (key: import('../../i18n/types/LocalizationKey.ts').ErrorKey) => string;
+    getLocalMonth: (key: string | undefined) => string;
     getLocalOption: (key: string | undefined, prefix?: string) => string | undefined;
+    getLocalPrompt: (key: string) => string;
     getLocalSubOption: (key: string | undefined) => string | undefined;
-    getLocalCountry: (key: string | undefined) => string;
+    getLocalSubPrompt: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => string;
+    getLocalSubTitle: (key: import('../../i18n/types/LocalizationKey.ts').SubTitleKey) => string;
+    getLocalText: (key: import('../../i18n/types/LocalizationKey.ts').TextKey) => string;
+    getLocalTitle: (key: string) => string;
     getLocalUsState: (key: string | undefined) => "" | "Alabama" | "Alaska" | "Arizona" | "Arkansas" | "California" | "Colorado" | "Connecticut" | "Delaware" | "District Of Columbia" | "Florida" | "Georgia" | "Hawaii" | "Idaho" | "Illinois" | "Indiana" | "Iowa" | "Kansas" | "Kentucky" | "Louisiana" | "Maine" | "Maryland" | "Massachusetts" | "Michigan" | "Minnesota" | "Mississippi" | "Missouri" | "Montana" | "Nebraska" | "Nevada" | "New Hampshire" | "New Jersey" | "New Mexico" | "New York" | "North Carolina" | "North Dakota" | "Ohio" | "Oklahoma" | "Oregon" | "Pennsylvania" | "Rhode Island" | "South Carolina" | "South Dakota" | "Tennessee" | "Texas" | "Utah" | "Vermont" | "Virginia" | "Washington" | "West Virginia" | "Wisconsin" | "Wyoming";
-    getLocalCaProvince: (key: string | undefined) => string;
-    getLocalMonth: (key: string | undefined) => string;
-    getLocalAddressTitle: (data: import('../../types/TaxDocumentation.ts').TaxDocumentation) => string;
     getPromptKey: (key: string) => import('../../i18n/types/LocalizationKey.ts').PromptKey;
     getSubPromptKey: (key: string) => import('../../i18n/types/LocalizationKey.ts').SubPromptKey;
     clearIfNotRequired: (...arg: import('../../types/TaxDocumentation.ts').TaxDocumentationKey[]) => (value: import('../../types/Yes.ts').Yes | undefined) => void;
@@ -64,4 +72,8 @@ export declare const useQuestionnaireStepContext: () => {
     hideField: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => void;
     showField: (key: import('../../types/TaxDocumentation.ts').TaxDocumentationKey) => void;
     dateFormat: import('../TaxDocumentation/useTaxDocumentation.ts').DateFormatConfig;
+    doVerify: () => Promise<void>;
+    isVerifying: boolean;
+    isDoneVerifying: boolean;
+    usTinValidations: import('../../hooks/index.ts').UsTinValidationAttempt[];
 } | undefined>;

package/dist/src/contexts/TaxDocumentation/TaxbitQuestionnaireProvider.d.ts

@@ -5,5 +5,5 @@ type TaxDocumentationProviderProps = UseTaxDocumentationProps & {
     children: React.ReactNode;
     treatyClaims?: boolean;
 };
-export declare const TaxbitQuestionnaireProvider: ({ data, externalValidations, onSubmit, onProgress, language, questionnaire, step, children, config, treatyClaims, dateFormat, }: TaxDocumentationProviderProps) => React.JSX.Element;
+export declare const TaxbitQuestionnaireProvider: ({ data, externalValidations, onSubmit, onProgress, language, questionnaire, step, children, config, treatyClaims, dateFormat, realTimeTinValidation, staging, bearerToken, }: TaxDocumentationProviderProps) => React.JSX.Element;
 export {};

package/dist/src/contexts/TaxDocumentation/useTaxDocumentation.d.ts

@@ -17,27 +17,35 @@ export type UseTaxDocumentationProps = {
     config?: InterviewConfig;
     treatyClaims?: boolean;
     dateFormat?: DateFormatConfig;
+    realTimeTinValidation?: boolean;
+    staging?: boolean;
+    bearerToken?: string;
 };
-export declare const useTaxDocumentation: ({ data: startingData, language: initialLanguage, externalValidations, onSubmit, onProgress, step: initialStep, questionnaire, config, treatyClaims, dateFormat, }: UseTaxDocumentationProps) => {
-    isBuildingW9: boolean;
+export declare const useTaxDocumentation: ({ data: startingData, language: initialLanguage, externalValidations, onSubmit, onProgress, step: initialStep, questionnaire, config, treatyClaims, dateFormat, realTimeTinValidation, staging, bearerToken, }: UseTaxDocumentationProps) => {
+    config: InterviewConfig | undefined;
+    data: TaxDocumentation;
+    dateFormat: DateFormatConfig;
+    doValidateUsTin: (name: string, usTin: string) => Promise<void>;
+    externalValidations: ExternalValidations | undefined;
+    goBack: (() => void) | undefined;
+    goTo: (inputStep: InputStep) => void;
+    goToNext: (data: TaxDocumentation) => void;
+    incrementValidationAttempt: (name: string, usTin: string) => void;
+    initialStep: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "AccountHolderUsTinValidation" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "RegardedOwnerUsTinValidation" | "Summary";
     isBuildingW8: boolean;
+    isBuildingW9: boolean;
+    isSubmitting: boolean;
+    isValidatingUsTin: boolean;
+    language: Locale;
     onPersistCollectedData: (newData: TaxDocumentation) => void;
     onSubmitTaxDocumentation: (data: TaxDocumentation) => Promise<void>;
-    goTo: (inputStep: InputStep) => void;
-    goBack: (() => void) | undefined;
-    goToNext: (data: TaxDocumentation) => void;
-    progress: Progress | undefined;
-    stepName: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "Summary";
-    data: TaxDocumentation;
     originalClientData: TaxDocumentation;
-    initialStep: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "Summary";
-    setLanguage: (lang: Locale) => void;
-    language: Locale;
+    progress: Progress | undefined;
     questionnaire: QuestionnaireProp;
-    externalValidations: ExternalValidations | undefined;
-    config: InterviewConfig | undefined;
-    isSubmitting: boolean;
+    realTimeTinValidation: boolean | undefined;
+    setLanguage: (lang: Locale) => void;
+    stepName: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "AccountHolderUsTinValidation" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "RegardedOwnerUsTinValidation" | "Summary";
     treatyClaims: boolean | undefined;
-    dateFormat: DateFormatConfig;
+    usTinValidations: import('../../hooks').UsTinValidationAttempt[];
 };
 export {};

package/dist/src/contexts/TaxDocumentation/useTaxDocumentationContext.d.ts

@@ -1,47 +1,57 @@
 export declare const useTaxDocumentationContext: () => {
-    isBuildingW9: boolean;
+    config: {
+        minimumAge: number;
+    } | undefined;
+    data: import('../../types').TaxDocumentation;
+    dateFormat: import('./useTaxDocumentation').DateFormatConfig;
+    doValidateUsTin: (name: string, usTin: string) => Promise<void>;
+    externalValidations: import('../../types/client').ExternalValidations | undefined;
+    goBack: (() => void) | undefined;
+    goTo: (inputStep: import('../../types').InputStep) => void;
+    goToNext: (data: import('../../types').TaxDocumentation) => void;
+    incrementValidationAttempt: (name: string, usTin: string) => void;
+    initialStep: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "AccountHolderUsTinValidation" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "RegardedOwnerUsTinValidation" | "Summary";
     isBuildingW8: boolean;
+    isBuildingW9: boolean;
+    isSubmitting: boolean;
+    isValidatingUsTin: boolean;
+    language: import('../..').Locale;
     onPersistCollectedData: (newData: import('../../types').TaxDocumentation) => void;
     onSubmitTaxDocumentation: (data: import('../../types').TaxDocumentation) => Promise<void>;
-    goTo: (inputStep: import('../../types').InputStep) => void;
-    goBack: (() => void) | undefined;
-    goToNext: (data: import('../../types').TaxDocumentation) => void;
-    progress: import('../..').Progress | undefined;
-    stepName: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "Summary";
-    data: import('../../types').TaxDocumentation;
     originalClientData: import('../../types').TaxDocumentation;
-    initialStep: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "Summary";
-    setLanguage: (lang: import('../..').Locale) => void;
-    language: import('../..').Locale;
+    progress: import('../..').Progress | undefined;
     questionnaire: import('../..').QuestionnaireProp;
-    externalValidations: import('../../types/client').ExternalValidations | undefined;
+    realTimeTinValidation: boolean | undefined;
+    setLanguage: (lang: import('../..').Locale) => void;
+    stepName: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "AccountHolderUsTinValidation" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "RegardedOwnerUsTinValidation" | "Summary";
+    treatyClaims: boolean | undefined;
+    usTinValidations: import('../../hooks').UsTinValidationAttempt[];
+}, TaxDocumentationContextProvider: import('react').Provider<{
     config: {
         minimumAge: number;
     } | undefined;
-    isSubmitting: boolean;
-    treatyClaims: boolean | undefined;
+    data: import('../../types').TaxDocumentation;
     dateFormat: import('./useTaxDocumentation').DateFormatConfig;
-}, TaxDocumentationContextProvider: import('react').Provider<{
-    isBuildingW9: boolean;
+    doValidateUsTin: (name: string, usTin: string) => Promise<void>;
+    externalValidations: import('../../types/client').ExternalValidations | undefined;
+    goBack: (() => void) | undefined;
+    goTo: (inputStep: import('../../types').InputStep) => void;
+    goToNext: (data: import('../../types').TaxDocumentation) => void;
+    incrementValidationAttempt: (name: string, usTin: string) => void;
+    initialStep: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "AccountHolderUsTinValidation" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "RegardedOwnerUsTinValidation" | "Summary";
     isBuildingW8: boolean;
+    isBuildingW9: boolean;
+    isSubmitting: boolean;
+    isValidatingUsTin: boolean;
+    language: import('../..').Locale;
     onPersistCollectedData: (newData: import('../../types').TaxDocumentation) => void;
     onSubmitTaxDocumentation: (data: import('../../types').TaxDocumentation) => Promise<void>;
-    goTo: (inputStep: import('../../types').InputStep) => void;
-    goBack: (() => void) | undefined;
-    goToNext: (data: import('../../types').TaxDocumentation) => void;
-    progress: import('../..').Progress | undefined;
-    stepName: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "Summary";
-    data: import('../../types').TaxDocumentation;
     originalClientData: import('../../types').TaxDocumentation;
-    initialStep: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "Summary";
-    setLanguage: (lang: import('../..').Locale) => void;
-    language: import('../..').Locale;
+    progress: import('../..').Progress | undefined;
     questionnaire: import('../..').QuestionnaireProp;
-    externalValidations: import('../../types/client').ExternalValidations | undefined;
-    config: {
-        minimumAge: number;
-    } | undefined;
-    isSubmitting: boolean;
+    realTimeTinValidation: boolean | undefined;
+    setLanguage: (lang: import('../..').Locale) => void;
+    stepName: "AccountHolderCertifications" | "AccountHolderClassification" | "AccountHolderContact" | "AccountHolderTax" | "AccountHolderTaxClarification" | "AccountHolderTreatyClaims" | "AccountHolderUsTinValidation" | "ControllingPersonDetails1" | "ControllingPersonDetails2" | "ControllingPersonDetails3" | "ControllingPersonDetails4" | "ControllingPersonDetails5" | "Exemptions" | "RegardedOwnerCertifications" | "RegardedOwnerContact" | "RegardedOwnerTax" | "RegardedOwnerTreatyClaims" | "RegardedOwnerUsTinValidation" | "Summary";
     treatyClaims: boolean | undefined;
-    dateFormat: import('./useTaxDocumentation').DateFormatConfig;
+    usTinValidations: import('../../hooks').UsTinValidationAttempt[];
 } | undefined>;

package/dist/src/hooks/index.d.ts

@@ -1,2 +1,3 @@
 export * from './useHandleError';
 export * from './useTaxbit';
+export * from './useUsTinVerification';

package/dist/src/hooks/useUsTinVerification/index.d.ts

@@ -0,0 +1 @@
+export * from './useUsTinValidation.ts';

package/dist/src/hooks/useUsTinVerification/useUsTinValidation.d.ts

@@ -0,0 +1,21 @@
+export type UsTinValidationStatus = 'invalidTin' | 'validTin' | 'pendingTin';
+export type UsTinValidationAttempt = {
+    name: string | undefined;
+    usTin: string | undefined;
+    status: UsTinValidationStatus;
+    attemptCount: number;
+};
+export type UsTinServerStatus = 'PENDING' | 'FOREIGN' | 'INVALID_DATA' | 'VALID_SSN_MATCH' | 'VALID_EIN_MATCH' | 'VALID_SSN_EIN_MATCH' | 'MISMATCH' | 'TIN_NOT_ISSUED' | 'ERROR';
+export declare const MAX_US_TIN_VALIDATION_ATTEMPTS = 3;
+type UseUsTinValidationProps = {
+    bearerToken?: string;
+    isEnabled?: boolean;
+    staging?: boolean;
+};
+export declare const useUsTinValidation: ({ bearerToken, isEnabled, staging, }: UseUsTinValidationProps) => {
+    doValidateUsTin: (name: string, usTin: string) => Promise<void>;
+    isValidatingUsTin: boolean;
+    usTinValidations: UsTinValidationAttempt[];
+    incrementValidationAttempt: (name: string, usTin: string) => void;
+};
+export {};

package/dist/src/i18n/json/en.json.d.ts

@@ -1,4 +1,9 @@
 declare const _default: {
+  "badge": {
+    "validTin": "Valid TIN Match",
+    "invalidTin": "Invalid TIN Match",
+    "pendingTin": "TIN Match Result Pending"
+  },
   "button": {
     "back": "Back",
     "cancel": "Cancel",
@@ -121,6 +126,8 @@ declare const _default: {
     "usPerson": "Are you a U.S. Person?",
     "usSsn": "Social Security Number",
     "usTin": "United States TIN",
+    "usTinIsValid": "Check this box to proceed with information that does not match IRS records",
+    "usTinMatchVerification": "U.S. TIN Verification",
     "usTrustEstateEin": "Does this trust/estate have an Employer Identification Number?",
     "usSoleProprietorEin": "Does this Sole Proprietorship have an Employer Identification Number?",
     "vatIdentificationNumber": "VAT Number",
@@ -202,7 +209,9 @@ declare const _default: {
     "signature": "Sign with the same name listed above",
     "signatureCapacityOther": "Describe the role in which you have capacity to sign.",
     "streetIsPermanent": "Enter your permanent street address. Do not use a PO Box or In-Care-of address.",
-    "usPerson": "An individual is a U.S. Person if they are a U.S. Citizen, U.S. Permanent Resident or has met the Substantial Presence Test. A business is a U.S. Person if they are organized or incorporated in the U.S."
+    "usPerson": "An individual is a U.S. Person if they are a U.S. Citizen, U.S. Permanent Resident or has met the Substantial Presence Test. A business is a U.S. Person if they are organized or incorporated in the U.S.",
+    "usTin": "The Name and TIN provided will be verified against the IRS database using the IRS TIN Matching e-Service.",
+    "usTinMatchVerification": "<p>The Name and TIN entered could not be verified with IRS records. Please review your information and make any necessary updates before proceeding.</p><p>Keep in mind that additional validation attempts may be limited, and failure to provide accurate information could result in processing delays.</p>"
   },
   "title": {
     "accountHolder": "Account Holder",
@@ -247,7 +256,9 @@ declare const _default: {
     "taxResidence4": "Tax Residency 4",
     "taxResidence5": "Tax Residency 5",
     "accountHolderTreatyClaims": "Claim of Tax Treaty Benefits",
-    "regardedOwnerTreatyClaims": "Claim of Tax Treaty Benefits"
+    "regardedOwnerTreatyClaims": "Claim of Tax Treaty Benefits",
+    "accountHolderUsTinValidation": "U.S. TIN Verification",
+    "regardedOwnerUsTinValidation": "U.S. TIN Verification"
   },
   "subTitle": {
     "taxResidences": "Enter each country or jurisdiction of which you are a tax resident.",
@@ -287,6 +298,7 @@ declare const _default: {
     "residencesMustIncludeAnEUCountry": "At least one country of tax residency must be an EU Country",
     "tooLong": "Too Long",
     "tooShort": "Too Short",
+    "usTinDoesNotMatchName": "The information you entered still doesn't match IRS records. Please either correct the information or confirm that the information provided is correct.",
     "vatinMustNotMatchResidencyTin": "VAT Number must not match Residency TIN"
   },
   "option": {

package/dist/src/i18n/json/es.json.d.ts

@@ -1,4 +1,9 @@
 declare const _default: {
+  "badge": {
+    "validTin": "Coincidencia de TIN válida",
+    "invalidTin": "Nombre/TIN no coinciden",
+    "pendingTin": "Resultado de coincidencia de TIN pendiente"
+  },
   "button": {
     "back": "Atrás",
     "cancel": "Cancelar",
@@ -115,6 +120,8 @@ declare const _default: {
     "usPerson": "¿Es una persona estadounidense?",
     "usSsn": "Número de la seguridad social",
     "usTin": "Número de identificación fiscal de EE. UU.",
+    "usTinMatchVerification": "Verificación de coincidencia de TIN de EE. UU.",
+    "usTinIsValid": "Marque esta casilla para continuar con información que no coincide con los registros del IRS",
     "usTrustEstateEin": "¿El fideicomiso/patrimonio tiene un EIN?",
     "usSoleProprietorEin": "¿El propietario único tiene un EIN?",
     "vatIdentificationNumber": "Número de IVA",
@@ -202,7 +209,9 @@ declare const _default: {
     "streetIsPermanent": "Si la dirección es permanente, seleccione \"Sí\". Si la dirección es temporal, seleccione \"No\".",
     "usPerson": "Una persona estadounidense es una persona que es ciudadana estadounidense, residente permanente de EE. UU. o ha cumplido con la \"Prueba de presencia sustancial\". Una empresa es una persona estadounidense si está organizada o incorporada en EE. UU.",
     "financialInstitutionType": "¿Qué tipo de institución financiera representa mejor el tipo de su cuenta?",
-    "role": "¿Cuál de las siguientes opciones representa mejor el rol por el cual esta persona es una Persona Controladora?"
+    "role": "¿Cuál de las siguientes opciones representa mejor el rol por el cual esta persona es una Persona Controladora?",
+    "usTin": "Se realizará una verificación a través del IRS para confirmar que el nombre y el TIN coinciden.",
+    "usTinMatchVerification": "<p>El nombre y el TIN ingresados serán verificados con el IRS. Por favor, revise y haga cambios si es necesario.</p><p>Proceda cuando todo esté correcto.</p>"
   },
   "subTitle": {
     "controllingPersonDetails": "Complete las siguientes preguntas para la persona de control a continuación.",
@@ -253,7 +262,9 @@ declare const _default: {
     "taxResidence2": "Domicilio fiscal 2",
     "taxResidence3": "Domicilio fiscal 3",
     "taxResidence4": "Domicilio fiscal 4",
-    "taxResidence5": "Domicilio fiscal 5"
+    "taxResidence5": "Domicilio fiscal 5",
+    "accountHolderUsTinValidation": "Verificación de TIN del IRS",
+    "regardedOwnerUsTinValidation": "Verificación de TIN del IRS"
   },
   "text": {
     "eSignActReference": "* La ley sobre las firmas electrónicas en el comercio mundial y nacional (Electronic Signatures in Global and National Commerce Act), 15 U.S.C. §7001 y siguientes (\"Ley de firma electrónica\") se aprobó el 30 de junio de 2000 y proporciona una norma general para la validación de firmas y registros electrónicos en transacciones comerciales interestatales o extranjeras o que sean determinantes para dicho comercio.",
@@ -287,6 +298,7 @@ declare const _default: {
     "required": "Necesario",
     "tooLong": "Demasiado largo",
     "tooShort": "Demasiado corto",
+    "usTinDoesNotMatchName": "El nombre y el TIN ingresados no pudieron ser verificados con los registros del IRS. Por favor, revise su información y realice las actualizaciones necesarias antes de continuar.",
     "vatinMustNotMatchResidencyTin": "El número de IVA no debe coincidir con el TIN"
   },
   "option": {

package/dist/src/i18n/json/fr.json.d.ts

@@ -1,4 +1,9 @@
 declare const _default: {
+  "badge": {
+    "validTin": "Correspondance TIN valide",
+    "invalidTin": "Non-correspondance nom/TIN",
+    "pendingTin": "Résultat de la correspondance TIN en attente"
+  },
   "button": {
     "back": "Retour",
     "cancel": "Annuler",
@@ -115,6 +120,8 @@ declare const _default: {
     "usPerson": "Êtes-vous une U.S. Person ?",
     "usSsn": "Numéro de sécurité sociale",
     "usTin": "Numéro d'identification fiscale US",
+    "usTinMatchVerification": "Vérification du NIF américain",
+    "usTinIsValid": "Cochez cette case pour continuer avec des informations qui ne correspondent pas aux dossiers de l'IRS",
     "usTrustEstateEin": "La fiducie/la succession dispose-t-elle d'un EIN ?",
     "usSoleProprietorEin": "L'entreprise individuelle dispose-t-elle d'un EIN ?",
     "vatIdentificationNumber": "Numéro d'identification TVA",
@@ -202,7 +209,9 @@ declare const _default: {
     "streetIsPermanent": "L'adresse principale est considérée comme permanente, sauf indication contraire.",
     "usPerson": "Un particulier est une U.S. Person s'il est citoyen américain, résident permanent américain ou s'il a satisfait au « Substantial Presence Test ». Une entreprise est une U.S. Person si elle est organisée ou incorporée aux États-Unis.",
     "financialInstitutionType": "Quel type d'institution financière représente le mieux votre type de compte?",
-    "role": "Lequel des éléments suivants représente le mieux le rôle en vertu duquel cette personne est une Personne de Contrôle?"
+    "role": "Lequel des éléments suivants représente le mieux le rôle en vertu duquel cette personne est une Personne de Contrôle?",
+    "usTin": "Une vérification sera effectuée auprès de l’IRS pour confirmer que le nom et le NIF correspondent.",
+    "usTinMatchVerification": "<p>Le nom et le NIF saisis seront vérifiés auprès de l’IRS. Veuillez vérifier et apporter des modifications si nécessaire.</p><p>Poursuivez lorsque tout semble correct.</p>"
   },
   "subTitle": {
     "controllingPersonDetails": "Complétez les questions suivantes pour la personne contrôlante ci-dessous.",
@@ -253,7 +262,9 @@ declare const _default: {
     "taxResidence2": "Résidence fiscale 2",
     "taxResidence3": "Résidence fiscale 3",
     "taxResidence4": "Résidence fiscale 4",
-    "taxResidence5": "Résidence fiscale 5"
+    "taxResidence5": "Résidence fiscale 5",
+    "accountHolderUsTinValidation": "Vérification du NIF américain du titulaire du compte",
+    "regardedOwnerUsTinValidation": "Vérification du NIF américain du titulaire du compte"
   },
   "text": {
     "eSignActReference": "* La loi sur les signatures électroniques dans le commerce mondial et national (Electronic Signatures in Global and National Commerce Act), 15 U.S.C. §7001, et seq. (« E-sign-Act ») a été promulguée le 30 juin 2000 et prévoit une règle générale pour la validation des enregistrements et des signatures électroniques pour les transactions dans ou affectant le commerce interétatique ou étranger.",
@@ -287,6 +298,7 @@ declare const _default: {
     "required": "Obligatoire",
     "tooLong": "Trop long",
     "tooShort": "Trop court",
+    "usTinDoesNotMatchName": "Le nom et le NIF saisis ne peuvent pas être vérifiés avec les dossiers de l'IRS. Veuillez vérifier vos informations et apporter les mises à jour nécessaires avant de continuer.",
     "vatinMustNotMatchResidencyTin": "Le numéro de TVA ne doit pas correspondre au TIN de résidence"
   },
   "option": {

package/dist/src/i18n/json/index.d.ts

@@ -0,0 +1,35 @@
+import { default as bgJson } from './bg.json';
+import { default as csJson } from './cs.json';
+import { default as daJson } from './da.json';
+import { default as deATJson } from './de-AT.json';
+import { default as deJson } from './de.json';
+import { default as elCYJson } from './el-CY.json';
+import { default as elJson } from './el.json';
+import { default as enGBJson } from './en-GB.json';
+import { default as enNZJson } from './en-NZ.json';
+import { default as enJson } from './en.json';
+import { default as esMXJson } from './es-MX.json';
+import { default as esJson } from './es.json';
+import { default as etJson } from './et.json';
+import { default as fiJson } from './fi.json';
+import { default as frCAJson } from './fr-CA.json';
+import { default as frLUJson } from './fr-LU.json';
+import { default as frJson } from './fr.json';
+import { default as gaJson } from './ga.json';
+import { default as hrJson } from './hr.json';
+import { default as huJson } from './hu.json';
+import { default as itJson } from './it.json';
+import { default as ltJson } from './lt.json';
+import { default as lvJson } from './lv.json';
+import { default as mtJson } from './mt.json';
+import { default as nlBEJson } from './nl-BE.json';
+import { default as nlJson } from './nl.json';
+import { default as noJson } from './no.json';
+import { default as plJson } from './pl.json';
+import { default as ptJson } from './pt.json';
+import { default as roJson } from './ro.json';
+import { default as skJson } from './sk.json';
+import { default as slJson } from './sl.json';
+import { default as svJson } from './sv.json';
+
+export { bgJson, csJson, daJson, deATJson, deJson, elCYJson, elJson, enGBJson, enJson, enNZJson, esJson, esMXJson, etJson, fiJson, frCAJson, frJson, frLUJson, gaJson, hrJson, huJson, itJson, ltJson, lvJson, mtJson, nlBEJson, nlJson, noJson, plJson, ptJson, roJson, skJson, slJson, svJson, };