tax-react-sdk

W-9/W-8 BEN Collection React SDK

Embeddable React components for collecting W-9 (U.S. persons) and W-8 BEN (foreign individuals) tax forms directly in your application's onboarding flow.

Installation

npm install tax-react-sdk
# or
yarn add tax-react-sdk

Quick Start

import { TaxFormQuestionnaire } from 'tax-react-sdk';
import 'tax-react-sdk/styles/inline.css';

function Onboarding() {
  const [bearerToken, setBearerToken] = useState('');

  useEffect(() => {
    // Fetch bearer token from your backend
    fetch('/api/w9/token', { method: 'POST' })
      .then(r => r.json())
      .then(data => setBearerToken(data.bearer_token));
  }, []);

  return (
    <TaxFormQuestionnaire
      bearerToken={bearerToken}
      formType="auto" // Shows W-9 vs W-8 BEN selector
      onSuccess={(result) => {
        console.log('Submitted!', result.submission_id);
        // Continue onboarding
      }}
    />
  );
}

Features

• ✅ Automatic Form Routing - Intelligently routes users to W-9 or W-8 BEN based on tax residency
• ✅ Multi-Step Forms - Clean, intuitive 5-step flow for each form type
• ✅ Pre-fill Support - Reduce friction by pre-filling known customer data
• ✅ Real-time Validation - Client-side validation with helpful error messages
• ✅ E-Signature Compliance - ESIGN Act compliant electronic signatures
• ✅ Responsive Design - Mobile-optimized, works on all screen sizes
• ✅ TypeScript Support - Full type definitions included
• ✅ Customizable Theming - Match your brand colors and fonts
• ✅ Multi-Language - Support for 40+ languages (coming soon)

API

<TaxFormQuestionnaire>

Main component for tax form collection.

Props

Prop	Type	Default	Description
bearerToken	string	Required	Bearer token from your backend
formType	'auto' | 'w9' | 'w8ben'	'auto'	Form type or automatic selection
language	string	'en-us'	Language code
prefillData	object	-	Pre-fill form fields
onSuccess	function	-	Called when form is submitted
onError	function	-	Called on submission error
onProgress	function	-	Called on step changes
onFormTypeSelected	function	-	Called when user selects form type
environment	'production' | 'sandbox'	'production'	API environment
theme	object	-	Custom theme colors
debug	boolean	false	Enable debug mode

Example with All Props

<TaxFormQuestionnaire
  bearerToken={token}
  formType="auto"
  language="en-us"
  prefillData={{
    name: 'John Smith',
    email: '[email protected]',
    address: '123 Main St',
  }}
  onSuccess={(result) => {
    console.log('Submission ID:', result.submission_id);
    console.log('Form Type:', result.form_type); // 'w9' or 'w8ben'
    console.log('TIN Match Status:', result.tin_match_status); // W-9 only
  }}
  onError={(error) => {
    console.error('Submission failed:', error);
  }}
  onProgress={(step, total) => {
    console.log(`Step ${step} of ${total}`);
  }}
  onFormTypeSelected={(formType) => {
    console.log('User selected:', formType);
  }}
  theme={{
    primaryColor: '#4F46E5',
    fontFamily: 'Inter, sans-serif',
    borderRadius: '8px',
  }}
  debug={process.env.NODE_ENV === 'development'}
/>

Form Types

W-9 Form (U.S. Persons)

For U.S. citizens, green card holders, and U.S. resident aliens.

Features:

• Automatic TIN matching with IRS
• TIN format validation (SSN vs EIN)
• Backup withholding certification

W-9 Form Fields

Field Name	Type	Required	Description
fullName	string	✅	Full name as shown on tax return
businessName	string	-	Business name/DBA (if different from above)
taxClassification	'individual' | 'c-corp' | 's-corp' | 'partnership' | 'trust-estate' | 'llc' | 'other'	✅	Federal tax classification
otherClassification	string	-	Required if taxClassification is 'other'
payeeExemptCode	string	-	Exempt payee code (if applicable)
fatcaExemptCode	string	-	FATCA exemption code (if applicable)
address	string	✅	Street address
city	string	✅	City
state	string	✅	State (2-letter code)
zipCode	string	✅	ZIP code
tin	string	✅	Tax Identification Number (SSN or EIN)
signatureName	string	✅	Full name for e-signature
esignConsent	boolean	✅	Must be true to submit

Example Pre-fill Data:

<TaxFormQuestionnaire
  bearerToken={token}
  prefillData={{
    fullName: 'John Smith',
    businessName: 'Smith Consulting LLC',
    taxClassification: 'llc',
    address: '123 Main Street',
    city: 'San Francisco',
    state: 'CA',
    zipCode: '94102',
    signatureName: 'John Smith'
  }}
/>

W-8 BEN Form (Foreign Individuals)

For foreign individuals receiving U.S.-source income.

Features:

• Country-specific validations
• Tax treaty article lookup
• 3-year form expiration tracking

W-8 BEN Form Fields

Field Name	Type	Required	Description
Part I: Identification
name	string	✅	Full name of beneficial owner
countryOfCitizenship	string	✅	ISO country code (e.g., 'MX', 'CA', 'GB')
permanentResidenceAddress	string	✅	Street address
permanentResidenceCity	string	✅	City
permanentResidenceCountry	string	✅	ISO country code
permanentResidencePostalCode	string	-	Postal/ZIP code
mailingAddress	string	-	If different from permanent
mailingCity	string	-	Mailing city
mailingCountry	string	-	ISO country code
mailingPostalCode	string	-	Postal code
dateOfBirth	string	✅	Format: 'YYYY-MM-DD'
Part II: Tax Identification
usTin	string	-	U.S. TIN (if applicable)
usTinType	'SSN' | 'ITIN' | 'EIN'	-	Type of U.S. TIN
foreignTin	string	-	Foreign tax ID number
foreignTinCountry	string	-	Country that issued foreign TIN
Part III: Treaty Benefits
claimTreatyBenefits	boolean	-	Whether claiming treaty benefits
treatyCountry	string	-	Country for treaty claim
treatyArticle	string	-	Treaty article number
withholdingRate	number	-	Withholding rate (e.g., 10 for 10%)
incomeType	string	-	Type of income (e.g., 'Interest', 'Dividends')
treatyExplanation	string	-	Additional treaty explanation
Part IV: Beneficial Owner
beneficialOwnerType	'individual' | 'government' | 'international-organization' | 'foreign-central-bank' | 'exempt-beneficial-owner' | 'other'	✅	Type of beneficial owner
Signature
signatureName	string	✅	Full name for e-signature
signingCapacity	string	-	Capacity in which acting
esignConsent	boolean	✅	Must be true to submit

Example Pre-fill Data:

<TaxFormQuestionnaire
  bearerToken={token}
  formType="w8ben"
  prefillData={{
    name: 'Juan Garcia',
    countryOfCitizenship: 'MX',
    permanentResidenceAddress: 'Av. Reforma 123',
    permanentResidenceCity: 'Mexico City',
    permanentResidenceCountry: 'MX',
    permanentResidencePostalCode: '01000',
    dateOfBirth: '1990-01-15',
    foreignTin: 'GAJU900115XXX',
    foreignTinCountry: 'MX',
    claimTreatyBenefits: true,
    treatyCountry: 'MX',
    treatyArticle: '10',
    withholdingRate: 10,
    incomeType: 'Interest',
    beneficialOwnerType: 'individual',
    signatureName: 'Juan Garcia'
  }}
/>

Styling

Three CSS options are available:

1. Inline Styles (Default)

Complete standalone styling with no external dependencies.

import 'tax-react-sdk/styles/inline.css';

2. Basic Styles

Minimal semantic styling, more customizable.

import 'tax-react-sdk/styles/basic.css';

3. Minimal Styles

Bare-bones structure only, bring your own styles.

import 'tax-react-sdk/styles/minimal.css';

Theming

Customize the look and feel to match your brand:

<TaxFormQuestionnaire
  bearerToken={token}
  theme={{
    primaryColor: '#FF6B6B',      // Your brand color
    fontFamily: 'Poppins, sans-serif',
    borderRadius: '12px',
    backgroundColor: '#FAFAFA',
    textColor: '#2C3E50',
  }}
/>

Backend Integration

1. Generate Bearer Token

Your backend must generate a bearer token for each user session.

// Example: Node.js/Express
const W9SDK = require('../lib/w9-sdk');

const w9sdk = new W9SDK(
  process.env.W9_CLIENT_ID,
  process.env.W9_CLIENT_SECRET
);

app.post('/api/w9/token', async (req, res) => {
  const user = req.user; // Your auth middleware

  // Create account owner
  const accountOwner = await w9sdk.createAccountOwner(
    user.id,
    user.email,
    user.name
  );

  // Generate bearer token for React SDK
  const bearerToken = await w9sdk.generateBearerToken(accountOwner.id);

  res.json({ bearer_token: bearerToken });
});

2. Poll Submission Status

After form submission, poll for status updates (TIN matching for W-9).

app.get('/api/w9/status/:submissionId', async (req, res) => {
  const status = await w9sdk.getSubmissionStatus(req.params.submissionId);
  res.json(status);
});

Response Types

W-9 Submission

{
  submission_id: string;
  form_type: 'w9';
  status: 'completed';
  tin_match_status: 'match' | 'no_match' | 'pending';
  submitted_at: string;
  document_url: string;
}

W-8 BEN Submission

{
  submission_id: string;
  form_type: 'w8ben';
  status: 'completed';
  treaty_claimed: boolean;
  treaty_country?: string;
  submitted_at: string;
  document_url: string;
  expires_at: string; // 3 years from submission
}

Environment Variables

Required on your backend:

W9_CLIENT_ID=w9_client_...
W9_CLIENT_SECRET=w9_secret_...
W9_API_BASE_URL=https://yourapp.com/api

Error Handling

<TaxFormQuestionnaire
  bearerToken={token}
  onError={(error) => {
    if (error.message.includes('expired')) {
      // Bearer token expired (>1 hour), regenerate
      refreshBearerToken();
    } else if (error.message.includes('network')) {
      // Network issue, retry
      retrySubmission();
    } else {
      // Show error to user
      showErrorModal(error.message);
    }
  }}
/>

TypeScript

Full TypeScript support with exported types:

import type {
  FormType,
  W9FormData,
  W8BENFormData,
  SubmissionResult,
  TaxFormQuestionnaireProps,
} from 'tax-react-sdk';

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Mobile browsers (iOS Safari 14+, Chrome Mobile)

License

MIT

Support

• Documentation: https://docs.yourapp.com
• Email: [email protected]
• Issues: https://github.com/yourorg/w9-sdk/issues

Development

Building

npm run build

Testing

npm test

Local Development

npm run dev

Changelog

v1.0.0 (Initial Release)

• ✅ W-9 form collection
• ✅ W-8 BEN form collection
• ✅ Automatic form routing
• ✅ TIN matching (W-9)
• ✅ E-signature compliance
• ✅ Custom theming
• ✅ TypeScript support

Roadmap

• Multi-language support (40+ locales)
• W-8 BEN-E (entities)
• W-8 ECI, W-8 EXP, W-8 IMY
• Document OCR (upload existing forms)
• Accessibility improvements (WCAG 2.1 AA)
• More payment processor integrations