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