KycWidget Integration

Use KycWidget to run the BigDataCorp identity wizard in your app — intro, basic data, a hosted document-capture iframe, address, review, and analyzing steps. The host owns user identity and navigation; the SDK has no account concept, so you pass the user’s email and wallet in and receive status updates back.

Approval is what unlocks Pods Ramp money movement. Once the profile reaches approved (with brlaEnabled: true), send the user into the RampWidget.

Install

Use the same package set and shared PodsWidgetProvider wrapper as EarnWidget, pinned to a version that includes the KYC widget:

pnpm add [email protected] @deframe-sdk/[email protected] @reduxjs/toolkit@^2 react-redux@^9 redux@^5

Import KycWidget from pods-sdk so it shares the same React context as the other widgets.

Styles and Theme

KycWidget follows the same styling model as EarnWidget: import @deframe-sdk/components/styles.css once and theme via PodsProvider.config.theme. See EarnWidget Styles and Theme. The widget renders a hosted BigDataIframe mid-flow for document capture.

Render the Wizard

Mount KycWidget inside the shared PodsWidgetProvider from the Earn guide. Pass the host-owned identity; the widget drives the linear wizard itself.

'use client'

import { KycWidget } from 'pods-sdk'
import { PodsWidgetProvider } from './PodsWidgetProvider'

export function KycPage({ email, walletAddress }: { email: string; walletAddress: string }) {
  return (
    <PodsWidgetProvider walletAddress={walletAddress}>
      <div className="pods-widget-slot" data-testid="kyc-widget">
        <KycWidget
          currentUserEmail={email}
          currentUserWalletAddress={walletAddress}
          autoHeight
          onSessionCreated={({ kycUserId, iframeUrl }) => persistSession(kycUserId, iframeUrl)}
          onStatusChange={(status) => syncKycStore(status)}
          onComplete={({ approved, redirectIntent }) => {
            if (approved) router.push(redirectIntent === 'withdraw' ? '/withdraw' : '/deposit')
          }}
        />
      </div>
    </PodsWidgetProvider>
  )
}

Host Identity and Resume

The SDK has no user store, so identity comes from the host:

currentUserEmail / currentUserWalletAddress — bind the KYC profile to your user.
initialKycUserId — resume an existing session (e.g. after a page refresh) instead of bootstrapping fresh.
onSessionCreated({ kycUserId, iframeUrl }) — fires right after a session is created; persist both so you can resume and reopen the capture iframe.
redirectIntent ('withdraw' | 'deposit') — where “continue” after approval should take the user; the widget never navigates itself, it reports the intent via onComplete / onRouteChange.

Status and Completion

onStatusChange(status: KycStatusResponse) — mirrors every status fetch into your own store.
onComplete({ approved, redirectIntent? }) — fires when the wizard reaches a decision.
errorMessageResolver(rawReason?) => string | undefined — host-owned copy for provider error reasons (defaults to pass-through).
onRequestSandboxReset — dev-only reset; wire it behind your own sandbox env check so the reset action never renders in production.
onTrack(event, props?) — analytics.

Status values progress: created → provider_pending → approved | rejected | rejected_retryable | blocked. brlaEnabled on the status response is the flag that unlocks Ramp.

`KycWidget` Props

type KycWidgetProps = {
  initialKycUserId?: string
  currentUserEmail?: string
  currentUserWalletAddress?: string
  redirectIntent?: 'withdraw' | 'deposit' | null
  onSessionCreated?: (session: { kycUserId: string; iframeUrl: string }) => void
  onStatusChange?: (status: KycStatusResponse) => void
  onComplete?: (outcome: { approved: boolean; redirectIntent?: 'withdraw' | 'deposit' | null }) => void
  onRequestSandboxReset?: () => Promise<void>   // dev/sandbox only
  onRouteChange?: (redirectTarget: string) => void
  onTrack?: (event: string, props?: Record<string, unknown>) => void
  errorMessageResolver?: (rawReason: string | undefined) => string | undefined
  // Layout
  className?: string
  style?: React.CSSProperties
  height?: string | number
  enableScroll?: boolean
  autoHeight?: boolean
}

API Endpoints Used in KYC Flows

POST /api/v1/kyc/bigdatacorp/sessions — create a session (returns kycUserId + hosted iframeUrl)
POST /api/v1/kyc/bigdatacorp/submit — submit applicant phone + address
GET /api/v1/kyc/status — poll the normalized status until terminal

Guides:

Next Step

Once the profile is approved, move money with the RampWidget.

Overview

Guides

Integrations

Agents

KycWidget Integration

Install

Styles and Theme

Render the Wizard

Host Identity and Resume

Status and Completion

`KycWidget` Props

API Endpoints Used in KYC Flows

Next Step

​Install

​Styles and Theme

​Render the Wizard

​Host Identity and Resume

​Status and Completion

​KycWidget Props

​API Endpoints Used in KYC Flows

​Next Step

Install

Styles and Theme

Render the Wizard

Host Identity and Resume

Status and Completion

`KycWidget` Props

API Endpoints Used in KYC Flows

Next Step