@boompay/screening

React components for Boom screening and identity verification flows.

Installation

npm install @boompay/screening
# or
yarn add @boompay/screening
# or
pnpm add @boompay/screening

Components

ScreeningFlow

A React component that displays Boom's screening application in an iframe with integrated Plaid Link support. This is the primary component for full screening flows including identity and income verification.

Features

• 🖥️ Iframe Integration: Embeds Boom screening application seamlessly
• 🌐 Multi-Environment Support: Works with development, production, and local environments
• ⚡ Plaid Integration: Automatic Plaid Link handoff for identity and income verification
• 🎯 TypeScript: Full TypeScript support with proper type definitions
• 🔄 Auto-Configuration: Handles configuration requests and responses automatically

Quick Start

import { ScreeningFlow } from "@boompay/screening";

function App() {
  const handleMessage = (event) => {
    // Handle messages from the screening application
    if (event.data.action === "close") {
      console.log("Received close action, closing SDK");
      // Close the SDK/iframe
    }
  };

  return (
    <ScreeningFlow
      env="sandbox"
      token="your-lead-token" // Optional
      onMessage={handleMessage}
      height="800px"
      width="100%"
    />
  );
}

Important: Before opening the SDK, ensure the application status is one of the following: "started" or "finished". Other statuses may result in unexpected behavior.

Props

| Prop | Type | Required | Description | | ------------- | ------------------------------- | -------- | -------------------------------------- | | env | "sandbox" \| "prod" \| string | ✅ | Environment configuration | | token | string | ❌ | Authentication token (WIP) | | onMessage | (event: MessageEvent) => void | ❌ | Callback for iframe postMessage events | | height | number \| string | ❌ | Height of the iframe (default: "100%") | | width | number \| string | ❌ | Width of the iframe (default: "100%") | | iFrameStyle | CSSProperties | ❌ | Custom styles for the iframe |

Environment Configuration

The env prop determines which screening application to load:

• "sandbox" → https://screen.sandbox.boompay.app (development/testing)
• "prod" → https://screen.boompay.app (currently disabled)

PostMessage Events

The screening application emits events that partners should listen for:

checkout_success Event

Emitted when the user successfully completes the checkout process. This event includes:

• Type: "checkout_success"

• Action: "close" - Partners should close the SDK/iframe upon receiving this event

• Payload:

• fee_in_cents (number): The application fee in cents. If 0, it indicates a free application.

TypeScript Type:

type CheckoutEvent = {
  type: "checkout_success";
  action: "close";
  payload: {
    // If 0 then it is a free application
    fee_in_cents: number;
  };
};

rental_qualification_rejected

Emitted if customer rejected rental qualifications

• Type: "rental_qualification_rejected"
• Action: "close" - Partners should close the SDK/iframe upon receiving this event

TypeScript Type:

type RentalQualificationRejectedEvent = {
  type: "rental_qualification_rejected";
  action: "close";
};

// BoomEvents is a union type of all possible events type BoomEvents = CheckoutEvent | InvalidTokenEvent | RentalQualificationRejectedEvent;

> **Note:** The `BoomEvents` type is exported from the package and represents all possible events emitted by the screening application:
>
> ```typescript
> import { BoomEvents, CheckoutEvent } from "@boompay/screening";
> ```

**Example handling:**

```tsx
import { ScreeningFlow, BoomEvents } from "@boompay/screening";

function App() {
  const handleMessage = (event: MessageEvent<BoomEvents>) => {
    if (event.data.type === "checkout_success") {
      const { fee_in_cents } = event.data.payload;

      console.log(`Checkout successful! Fee: $${fee_in_cents / 100}`);

      if (fee_in_cents === 0) {
        console.log("This was a free application");
      }

      // Close the SDK/iframe as indicated by action: "close"
      // Your logic to close the component
    }
  };

  return (
    <ScreeningFlow
      env="sandbox"
      token="your-lead-token"
      onMessage={handleMessage}
    />
  );
}

##### Events with `action: "close"`

Several events include an `action: "close"` property, indicating that partners should close the SDK/iframe.

#### Advanced Usage

##### Custom Styling

```tsx
<ScreeningFlow
  env="sandbox"
  height={600}
  width="90%"
  iFrameStyle={{
    border: "2px solid #007bff",
    borderRadius: "12px",
    boxShadow: "0 4px 6px rgba(0, 0, 0, 0.1)"
  }}
/>

IdentityFlow

A React component that integrates with Plaid for identity verification. It handles authentication, token creation, and Plaid Link initialization automatically.

Features

• 🔐 Automatic Authentication: Handles lead token authentication
• 🌐 Multi-Environment Support: Works with sandbox and local development (production currently disabled)
• ⚡ Plaid Integration: Seamless Plaid Link integration for identity verification
• 🧹 Memory Safe: Proper cleanup to prevent memory leaks and race conditions
• 📱 Loading States: Customizable loading UI during API requests
• 🎯 TypeScript: Full TypeScript support with proper type definitions

Quick Start

import { IdentityFlow } from "@boompay/screening";

function App() {
  return (
    <IdentityFlow
      token="your-lead-token"
      env="sandbox"
      LoadingView={<div>Loading identity verification...</div>}
      onSuccess={(data) => {
        console.log("Identity verification successful:", data);
        // Handle successful verification
      }}
      onError={(error) => {
        console.error("Identity verification failed:", error);
        // Handle errors
      }}
      onSkipped={(reason) => {
        console.log("Identity verification skipped:", reason);
        // Handle when IDV is already completed
      }}
      onExit={() => {
        console.log("User exited identity verification");
        // Handle user exit
      }}
    />
  );
}

Props

All props are required except onEvent:

| Prop | Type | Required | Description | | ------------- | ------------------------------------------------ | -------- | ------------------------------------------------------------------------------- | | token | string | ✅ | Lead token for authentication | | onSuccess | (data: PlaidLinkOnSuccessMetadata) => void | ✅ | Callback called with Plaid data on successful completion | | onError | (error: string) => void | ✅ | Callback called when generating create token failed or when Plaid emits onError | | onSkipped | (reason: 'lead_idv_already_submitted') => void | ✅ | Callback called when IDV is skipped (already completed for this lead) | | onExit | () => void | ✅ | Callback triggered when Plaid is closed | | onEvent | PlaidLinkOnEvent | ❌ | Called for every Plaid Link event (for logging/telemetry). See below. | | env | "sandbox" \| "prod" \| string | ✅ | Environment to use for API calls (prod currently disabled) | | LoadingView | React.ReactNode | ✅ | React node displayed while making API requests |

Plaid Events (onEvent)

The optional onEvent callback is invoked for every event Plaid Link emits during the identity verification flow. It receives the raw Plaid eventName and metadata and fires for all events before any internal flow handling, making it the single hook for logging and telemetry.

It mirrors Plaid Link's native onEvent signature:

import type {
  PlaidLinkOnEvent,
  PlaidLinkOnEventMetadata
} from "@boompay/screening";

type PlaidLinkOnEvent = (
  eventName: PlaidLinkStableEvent | string,
  metadata: PlaidLinkOnEventMetadata
) => void;

Stable event names (PlaidLinkStableEvent, exported from the package — safe to switch on; will not be deprecated or renamed):

| Event name | When it fires | | ------------------------------------ | -------------------------------------------------------- | | OPEN | Link opened | | SELECT_INSTITUTION | User selected a financial institution | | HANDOFF | Link is handing off to the institution | | ERROR | An error occurred (also surfaced via onError) | | EXIT | User exited Link (also surfaced via onExit) | | BANK_INCOME_INSIGHTS_COMPLETED | Bank income insights completed | | IDENTITY_VERIFICATION_PASS_SESSION | Identity verification session passed | | IDENTITY_VERIFICATION_FAIL_SESSION | Identity verification session failed |

In addition to the stable events above, Plaid emits informational events (e.g. TRANSITION_VIEW, SUBMIT_CREDENTIALS, SEARCH_INSTITUTION). These are also forwarded to onEvent but, per Plaid, are subject to change and should not be used to drive product behavior — log them, don't branch on them. See Plaid's onEvent reference for the full list and the metadata fields.

Example — logging every event:

import { IdentityFlow } from "@boompay/screening";
import type { PlaidLinkOnEventMetadata } from "@boompay/screening";

<IdentityFlow
  token={leadToken}
  env="sandbox"
  LoadingView={<div>Loading…</div>}
  onSuccess={handleSuccess}
  onError={handleError}
  onSkipped={handleSkipped}
  onExit={handleExit}
  onEvent={(eventName: string, metadata: PlaidLinkOnEventMetadata) => {
    // Forward to your logger / analytics. Avoid logging PII.
    logger.info("plaid_idv_event", {
      eventName,
      view_name: metadata.view_name,
      error_type: metadata.error_type,
      error_code: metadata.error_code,
      link_session_id: metadata.link_session_id,
      request_id: metadata.request_id,
      timestamp: metadata.timestamp
    });
  }}
/>;

Environment Configuration

The env prop determines which API endpoint to use:

• "sandbox" → https://api.sandbox.boompay.app (development/testing)
• "prod" → https://api.production.boompay.app (production)

Error Handling

The component handles various error scenarios and calls onError with specific messages:

• "no lead token" - When no token is provided
• "unauthorized" - When authentication fails
• "unable to create identity token" - When link token creation fails
• "unable to finish identity verification" - When the finish step fails after Plaid success
• Plaid-specific errors are passed through from the Plaid Link

Flow Diagram

flowchart TD
    A[Component Mounts] --> B{Token Provided?}
    B -->|No| C[onError: 'no lead token']
    B -->|Yes| D[Show LoadingView]
    D --> E[POST /screen/auth_with_token]
    E --> F{Auth Success?}
    F -->|No| G[onError: 'unauthorized']
    F -->|Yes| H[POST /screen/leads/identity_verifications]
    H --> I{Response Status?}
    I -->|418| J[onSkipped: 'lead_idv_already_submitted']
    I -->|Other Error| K[onError: 'unable to create identity token']
    I -->|Success| L[Initialize Plaid Link]
    L --> M[Open Plaid Flow]
    M --> N{User Action}
    N -->|Success| O[POST /screen/leads/identity_verifications/finish]
    N -->|Error| P[onError with Plaid error]
    N -->|Exit| Q[onExit]
    O --> R{Finish Success?}
    R -->|No| S[onError: 'unable to finish identity verification']
    R -->|Yes| T[onSuccess with metadata]

Advanced Usage

Custom Loading Component

const CustomLoader = (
  <div className="flex items-center justify-center p-8">
    <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600"></div>
    <span className="ml-3 text-gray-600">Connecting to Boom...</span>
  </div>
);

<IdentityFlow
  token={leadToken}
  env="sandbox"
  LoadingView={CustomLoader}
  // ... other props
/>;

TypeScript Support

The component is fully typed with TypeScript. Import the types for better development experience:

import {
  IdentityFlow,
  type IdentityFlowProps,
  type PlaidLinkOnSuccessMetadata
} from "@boompay/screening";

const handleSuccess = (data: PlaidLinkOnSuccessMetadata) => {
  // TypeScript will provide full intellisense for the data object
  console.log(data.accounts, data.institution, data.link_session_id);
};

Troubleshooting

Component doesn't load Plaid

• Verify your lead token is valid
• Check network connectivity to the Boom API
• Ensure the correct environment is selected

"unauthorized" error

• The lead token may be expired or invalid
• Verify the token format matches expected structure

"unable to create identity token" error

• API may be down or unreachable
• Check if the authentication step succeeded
• Verify network permissions for the target environment

Plaid errors

• These are passed through from Plaid Link
• Check Plaid's documentation for specific error codes
• Verify Plaid is properly configured for your environment