@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:

| Prop | Type | 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 | | env | "sandbox" \| "prod" \| string | Environment to use for API calls (prod currently disabled) | | LoadingView | React.ReactNode | React node displayed while making API requests |

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