larkfinserv-react-native-sdk

React Native SDK for integrating Lark FinServ loan journeys in Android and iOS apps.

Overview

This SDK supports:

• Session initialization using API credentials
• Loan journey rendering in WebView (inline or modal/embedded)
• External browser opening (popup mode)
• Journey event callbacks (READY, ELIGIBILITY_RESULT, ERROR, etc.)
• Native deep-link callback handling for KYC, mandate, and agreement completion
• Runtime callback URL updates with appRedirectionUrl

Installation

npm install larkfinserv-react-native-sdk

or

yarn add larkfinserv-react-native-sdk

Required peer/runtime dependency:

npm install react-native-webview

iOS only:

cd ios && pod install && cd ..

Quick Start

import React, { useEffect, useMemo, useState } from 'react';
import { View, Button } from 'react-native';
import {
  LarkFinServSDK,
  LarkFinServWebView,
  useDeepLinkHandler,
  type RedirectionEventData,
} from 'larkfinserv-react-native-sdk';

const APP_SCHEME = 'myapp';
const CALLBACK_PATH = '/callback';

export default function LoanScreen() {
  const [showSDK, setShowSDK] = useState(false);

  const sdk = useMemo(
    () =>
      new LarkFinServSDK({
        apiKey: 'your-api-key',
        apiSecret: 'your-api-secret',
        environment: 'sandbox',
      }),
    []
  );

  const { getCallbackUrl } = useDeepLinkHandler({
    urlScheme: APP_SCHEME,
    callbackPath: CALLBACK_PATH,
    onRedirectionEvent: (data: RedirectionEventData) => {
      sdk.handleRedirectionCallback(data);
    },
  });

  useEffect(() => {
    const init = async () => {
      await sdk.initialize({
        appRedirectionUrl: getCallbackUrl(APP_SCHEME, CALLBACK_PATH),
      });
    };
    init();
    return () => sdk.destroy();
  }, [sdk, getCallbackUrl]);

  const open = () => {
    sdk.setAppRedirectionUrl(getCallbackUrl(APP_SCHEME, CALLBACK_PATH));
    setShowSDK(true);
  };

  return (
    <View style={{ flex: 1 }}>
      <Button title="Open SDK" onPress={open} />
      {showSDK && (
        <LarkFinServWebView
          sdk={sdk}
          mode="embedded"
          visible={showSDK}
          onClose={() => setShowSDK(false)}
        />
      )}
    </View>
  );
}

Modes

Inline mode

Render SDK inside your current screen without modal wrapper.

<LarkFinServWebView sdk={sdk} mode="inline" />

Embedded mode

Render SDK in full-screen modal.

<LarkFinServWebView
  sdk={sdk}
  mode="embedded"
  visible={showSDK}
  onClose={() => setShowSDK(false)}
/>

Popup mode

Open journey URL in external browser.

await sdk.openEligibilityCheck('popup');

Use popup mode only after setting appRedirectionUrl and native deep-link registration.

Callback Redirection and Deep Linking

The SDK supports callback events for:

• KYC_COMPLETED
• MANDATE_COMPLETED
• LOAN_AGREEMENT_COMPLETED

Required setup

These must match exactly:

1. App scheme in native platform config
2. Scheme used in useDeepLinkHandler({ urlScheme })
3. Scheme used when generating callback URL
4. appRedirectionUrl passed to SDK

Callback URL format

• Native: myapp://callback
• Example: myloanapp://callback?type=KYC_COMPLETED&status=success
• Android (recommended): myapp://callback?androidPackage=com.example.myapp

Android package hint (recommended)

When Android cannot resolve a deep link target reliably, users may be sent to Play Store. To avoid this, include your package in appRedirectionUrl:

const baseCallbackUrl = getCallbackUrl(APP_SCHEME, CALLBACK_PATH);
const callbackUrl =
  Platform.OS === 'android'
    ? `${baseCallbackUrl}?androidPackage=com.example.myapp`
    : baseCallbackUrl;

sdk.setAppRedirectionUrl(callbackUrl);

Android manifest snippet

<activity android:name=".MainActivity" android:launchMode="singleTask" android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="myapp" />
  </intent-filter>
</activity>

iOS Info.plist snippet

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.example.myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Runtime pattern (recommended)

Always set callback URL before opening a flow:

const baseCallbackUrl = getCallbackUrl(APP_SCHEME, '/callback');
const callbackUrl =
  Platform.OS === 'android'
    ? `${baseCallbackUrl}?androidPackage=com.example.myapp`
    : baseCallbackUrl;
sdk.setAppRedirectionUrl(callbackUrl);

API Reference

LarkFinServSDK

Constructor

const sdk = new LarkFinServSDK(config: PartnerConfig);

Methods

initialize(config?: Partial<PartnerConfig>): Promise<void>

• Initializes SDK session
• Accepts partial updates after constructor

openEligibilityCheck(mode: SDKMode): Promise<void>

• For popup, opens external browser
• For other modes, emits initiation event for WebView usage

getIframeUrl(): string

• Returns generated journey URL for WebView

setAppRedirectionUrl(url: string): void

• Updates callback URL at runtime
• Regenerates iframe URL when session exists

handleRedirectionCallback(data: RedirectionEventData): void

• Forwards parsed deep-link callback payload to SDK events

handleIncomingUrl(url: string, callbackPath?: string): RedirectionEventData | null

• Parses callback URL and emits callback event

startDeepLinkListener(callbackPath?: string, onRedirectionEvent?: (data) => void): () => void

• Starts Linking listener and processes initial URL
• Returns cleanup function

stopDeepLinkListener(): void

• Stops listener created above

on(event, handler): void

• Registers event handler

off(event): void

• Removes event handler for that event type

clearSession(): void

• Emits session cleared event and resets state externally

getSessionInfo(): object

• Returns current session indicators and IDs

destroy(): void

• Cleans listeners and handlers; call on unmount

LarkFinServWebView

Props:

• sdk: LarkFinServSDK (required)
• mode: 'inline' | 'embedded' (default: inline)
• visible?: boolean (embedded mode)
• onClose?: () => void
• containerStyle?: StyleProp<ViewStyle>

useDeepLinkHandler(options?)

Options:

• urlScheme?: string
• callbackPath?: string (default /callback)
• onRedirectionEvent?: (data) => void
• onError?: (error) => void

Returns:

• lastRedirectionData
• isProcessing
• handleIncomingUrl(url)
• clearCallbackData()
• getCallbackUrl(baseScheme?, callbackPath?)
• isNative

Types

PartnerConfig

interface PartnerConfig {
  apiKey: string;
  apiSecret: string;
  environment?: 'sandbox' | 'production';
  partnerId?: string;
  partnerName?: string;
  userId?: string;
  userData?: Record<string, unknown>;
  sessionId?: string;
  phoneNumber?: string;
  appRedirectionUrl?: string;
  consentData?: {
    privacyConsent: boolean;
    promotionalConsent: boolean;
  };
  theme?: {
    primaryColor?: string;
    secondaryColor?: string;
    fontFamily?: string;
    logoUrl?: string;
    name?: string;
  };
}

RedirectionEventData

interface RedirectionEventData {
  type: 'KYC_COMPLETED' | 'MANDATE_COMPLETED' | 'LOAN_AGREEMENT_COMPLETED';
  status: 'success' | 'error' | 'pending';
  timestamp?: number;
  message?: string;
  digioDocId?: string;
  kycStatus?: string;
  mandateId?: string;
  mandateStatus?: string;
  agreementId?: string;
}

Events

Supported event names:

• INITIATED
• READY
• ELIGIBILITY_RESULT
• ERROR
• CLOSE
• CLOSE_FRAME
• JOURNEY_STEP_COMPLETED
• SESSION_CLEARED
• KYC_COMPLETED
• MANDATE_COMPLETED
• LOAN_AGREEMENT_COMPLETED

Example:

sdk.on('ERROR', (event) => {
  console.log(event.data?.error?.message);
});

sdk.on('KYC_COMPLETED', (event) => {
  console.log('KYC callback payload', event.data);
});

Integration Patterns

Pattern A: Embedded modal only

• Initialize once on screen load
• Use LarkFinServWebView with mode="embedded"
• Update callback URL before each open

Pattern B: Inline in screen layout

• Render mode="inline" inside dedicated screen area
• Useful when journey is part of larger screen UI

Pattern C: External browser return flow

• Use openEligibilityCheck('popup')
• Mandatory deep-link setup on Android/iOS
• Mandatory appRedirectionUrl with matching scheme

Troubleshooting

App does not return after browser completion

Check:

1. Native scheme registration exists
2. appRedirectionUrl uses same scheme
3. useDeepLinkHandler uses same scheme/path
4. Callback URL includes type and status

Callback event not emitted

Check:

1. onRedirectionEvent calls sdk.handleRedirectionCallback(data)
2. Screen is still mounted and not destroyed early
3. URL parser receives valid query params

WebView blank

Check:

1. SDK initialized before rendering WebView
2. Network access available
3. Credentials and environment are correct

iOS build issues

Run:

cd ios && pod install

Android deep-link verification

adb shell am start -W -a android.intent.action.VIEW -d "myapp://callback?type=KYC_COMPLETED&status=success"

If app does not open, native deep-link setup is incomplete.

Production Checklist

1. Do not hardcode secrets in source
2. Keep app scheme/path constants in one place
3. Call setAppRedirectionUrl before each flow open
4. Handle ERROR and close events
5. Call sdk.destroy() on unmount
6. Validate deep-link behavior on both Android and iOS
7. Test all three callback types in sandbox before release

Local Demo App

Standalone demo app using local package:

• ../larkfinserv-reactnative-demo

This app demonstrates end-to-end deep-link callback handling with app scheme.

Support

• Email: [email protected]
• Issues: https://github.com/larkfinserv/larkfinserv-react-native-sdk/issues