[Alpha] Personal Loans

React Native Web Wrapper SDK — Personal Loans Integration Guide (Alpha)

Overview

The Web Wrapper delivers the Personal Loans marketplace flow as an embedded widget, sharing one implementation across multiple tech stacks. This page covers installation, prerequisites, the core configuration props (channel, zone, productTypes), a basic usage example, prefilling lead data, client tags, and event handlers.

This approach is in [Alpha] while we finalize the cross-stack API. For production React Native personal loan integrations today, we recommend the native Personal Loans SDK.

You'll need the correct channel and zone values for your integration. Ask your Partner Manager to provide these values for Personal Loans.

Before you start, request an API token from your Partner Manager. It authenticates with the Engine API and is required to use the Prefill API. You may want multiple tokens depending on how many entry points your app has into the SDK.

Requirements

• React Native

Install

Install the SDK from npm using your package manager:

• npm install --save @moneylion/react-native-web-wrapper

• yarn add @moneylion/react-native-web-wrapper

Initialize

Import the WebWrapper component into any file where you want to render the Engine flow:

import { WebWrapper, ApiModels } from '@moneylion/react-native-web-wrapper';

Basic Example

<WebWrapper
  channel="your-channel"
  zone="your-zone"
  productTypes={[ApiModels.ProductType.Loan]}
  onExit={() => {
    // handle exit / navigation
  }}
  // ...optional event handlers, see Event Handlers
/>

Properties

Prop	Type	Required	Description
channel	string	Yes	Identifies your integration in Engine. Provided by your Partner Manager (e.g. 'direct').
zone	string	Yes	Identifies the placement or distribution surface for the SDK. Provided by your Partner Manager (e.g. 'marketplace').
productTypes	ApiModels.ProductType[]	Yes	Product flow(s) to render. Use [ApiModels.ProductType.Loan] for Personal Loans.
bearerToken	string	For prefill	API token from your Partner Manager. Required to use the Prefill API. Without it, the standard non-prefilled flow renders.
isDev	boolean	No	When true, the SDK targets Engine's dev/staging hosts. Defaults to false (production).
style	ViewStyle	No	Style applied to the underlying view, e.g. {{ height: '100%' }}.
personalInformation, loanInformation, mortgageInformation, creditInformation, financialInformation, employmentInformation, legalInformation, educationInformation	Lead*Information	No	Prefill data. See Prefilling Lead Data.
clientTags	Record<string, string[]>	No	Reporting/attribution tags. See Client Tags.
onExit	OnExitCallback	Yes	Fired when the user exits the flow.
onInitialize, onCreate, onUpdate, onNavigate, onSubmit, onRateTableRender, onOfferClick, onErrorPageView, onErrorPageRetry, onEmbedError, onEmbedErrorRetry	(props) => void	No	Optional tracking hooks. See Event Handlers.

Prefilling Lead Data

Prefill any user data you already have to reduce what the user has to type in-flow. Prefilled data is grouped into typed information objects, each passed as its own prop on WebWrapper (e.g. personalInformation, loanInformation, financialInformation).

Prefilling requires a bearerToken. Pass only the fields you have — omitted fields are collected from the user in-flow.

Example

<WebWrapper
  channel="your-channel"
  zone="your-zone"
  bearerToken="{your_token}"
  productTypes={[ApiModels.ProductType.Loan]}
  personalInformation={{
    firstName: 'Bob',
    lastName: 'Dylan',
    email: '[email protected]',
    dateOfBirth: '1990-01-01', // YYYY-MM-DD
    primaryPhone: '2325624852',
    address1: '1600 Pennsylvania Avenue',
    address2: 'Apt 2',
    city: 'Washington',
    state: 'DC',
    zipcode: '20500',
    ssn: '512-54-7862',
  }}
  loanInformation={{
    purpose: ApiModels.LoanPurpose.CreditCardRefi,
    loanAmount: 7500,
  }}
  mortgageInformation={{
    propertyStatus: ApiModels.PropertyStatus.OwnWithMortgage,
  }}
  creditInformation={{
    providedCreditRating: ApiModels.ProvidedCreditRating.Good,
  }}
  financialInformation={{
    employmentStatus: ApiModels.EmploymentStatus.EmployedFullTime,
    employmentPayFrequency: ApiModels.EmploymentPayFrequency.Biweekly,
    annualIncome: 20000,
    creditCardDebt: 5000,
    bankRoutingNumber: '123456789',
    bankAccountNumber: '55555555555',
  }}
  employmentInformation={{
    directDeposit: false,
  }}
  legalInformation={{
    consentsToSms: true,
  }}
  educationInformation={{
    educationLevel: ApiModels.EducationLevel.Associate,
  }}
  onExit={(evt) => console.log('onExit', evt)}
/>

Type Definitions

Every prop and field is optional — pass only what you have.

interface LeadPersonalInformation {
  firstName?: string;
  lastName?: string;
  email?: string;
  dateOfBirth?: string; // YYYY-MM-DD
  primaryPhone?: string; // 10 digits, no "+" or "-" chars
  address1?: string;
  address2?: string; // optional apartment / suite
  city?: string;
  state?: string; // 2-letter code, e.g. 'DC'
  zipcode?: string;
  ssn?: string; // 9 digits with or without hyphens
}

interface LeadLoanInformation {
  purpose?: ApiModels.LoanPurpose; // enum below
  loanAmount?: number; // whole numbers only
}

interface LeadMortgageInformation {
  propertyStatus?: ApiModels.PropertyStatus; // enum below
}

interface LeadCreditInformation {
  providedCreditRating?: ApiModels.ProvidedCreditRating; // enum below
}

interface LeadFinancialInformation {
  employmentStatus?: ApiModels.EmploymentStatus; // enum below
  employmentPayFrequency?: ApiModels.EmploymentPayFrequency; // enum below
  annualIncome?: number; // raw integer value (e.g. 20000)
  creditCardDebt?: number; // total credit card debt, raw integer value
  bankRoutingNumber?: string; // must be exactly 9 digits
  bankAccountNumber?: string;
}

interface LeadEmploymentInformation {
  directDeposit?: boolean;
}

interface LeadLegalInformation {
  consentsToSms?: boolean; // lead agrees to receive SMS
}

interface LeadEducationInformation {
  educationLevel?: ApiModels.EducationLevel; // enum below
}

Enums / Accepted Values

Use a member of the corresponding ApiModels enum (access via the ApiModels namespace, e.g. ApiModels.LoanPurpose.CreditCardRefi):

enum LoanPurpose {
  Auto = 'auto',
  AutoPurchase = 'auto_purchase',
  AutoRefinance = 'auto_refinance',
  Baby = 'baby',
  Boat = 'boat',
  Business = 'business',
  CarRepair = 'car_repair',
  Cosmetic = 'cosmetic',
  CreditCardRefi = 'credit_card_refi',
  DebtConsolidation = 'debt_consolidation',
  Emergency = 'emergency',
  Engagement = 'engagement',
  Green = 'green',
  HomeImprovement = 'home_improvement',
  HomePurchase = 'home_purchase',
  HomeRefi = 'home_refi',
  HouseholdExpenses = 'household_expenses',
  LargePurchases = 'large_purchases',
  LifeEvent = 'life_event',
  MedicalDental = 'medical_dental',
  Motorcycle = 'motorcycle',
  MovingRelocation = 'moving_relocation',
  Other = 'other',
  Rv = 'rv',
  SpecialOccasion = 'special_occasion',
  StudentLoan = 'student_loan',
  StudentLoanRefi = 'student_loan_refi',
  Taxes = 'taxes',
  Vacation = 'vacation',
  Wedding = 'wedding',
}

enum ProvidedCreditRating {
  Excellent = 'excellent',
  Good = 'good',
  Fair = 'fair',
  Poor = 'poor',
  Limited = 'limited',
}

enum PropertyStatus {
  OwnOutright = 'own_outright',
  OwnWithMortgage = 'own_with_mortgage',
  Rent = 'rent',
}

enum EducationLevel {
  HighSchool = 'high_school',
  Associate = 'associate',
  Bachelors = 'bachelors',
  Masters = 'masters',
  Doctorate = 'doctorate',
  OtherGradDegree = 'other_grad_degree',
  Certificate = 'certificate',
  DidNotGraduate = 'did_not_graduate',
  StillEnrolled = 'still_enrolled',
  Other = 'other',
}

enum EmploymentStatus {
  Employed = 'employed',
  EmployedFullTime = 'employed_full_time',
  EmployedPartTime = 'employed_part_time',
  Military = 'military',
  NotEmployed = 'not_employed',
  SelfEmployed = 'self_employed',
  Retired = 'retired',
  Other = 'other',
}

enum EmploymentPayFrequency {
  Biweekly = 'biweekly',
  Monthly = 'monthly',
  TwiceMonthly = 'twice_monthly',
  Weekly = 'weekly',
}

// state is a 2-letter US state code, e.g. 'CA', 'DC', 'NY'

Do not prefill any fields that are empty or unavailable — omit them so the user is prompted in-flow. Prefilled data must match the type definitions above, and any field backed by an enum must use a valid value. If a value is invalid, that attribute is stripped and the user will have to enter it again manually.

Client Tags

The Engine Web Wrapper SDK supports adding your unique Client Tags to track performance of specific campaigns or users. All Client Tag data is attributed to the lead level.

Client Tags are added via the clientTags prop, a map of string keys to lists of string values. We strongly recommend including only one element per list for ease of reporting and attribution — if you want two separate tags, include the second tag under a different key. There is no limit to the number of keys.

<WebWrapper
  channel="your-channel"
  zone="your-zone"
  bearerToken="{your_token}"
  productTypes={[ApiModels.ProductType.Loan]}
  personalInformation={{ /* ...any data you don't want to ask for again */ }}
  clientTags={{
    clientId: ['client1'],
    trafficsource: ['email'],
    campaignId: ['campaign1'],
  }}
  // ...optional Event Handlers, see below
/>

Note: Client Tags are only sent as part of a prefill request. You must provide both a bearerToken and prefill data (via the information props such as personalInformation). If no prefill data is supplied, the SDK makes no prefill call and any clientTags you pass are ignored.

Event Handlers

The WebWrapper component exposes optional event callback props that notify your app when key moments occur during the user's journey. Each callback receives an event object containing a timestamp (ISO 8601 UTC) and event-specific fields.

All callbacks are optional. If a callback is not provided, the SDK will still log the event to the debug console in development mode.

<WebWrapper
  channel="your-channel"
  zone="your-zone"
  bearerToken="{your_token}"
  productTypes={[ApiModels.ProductType.Loan]}
  onInitialize={(evt) => console.log('onInitialize', evt)}
  onCreate={(evt) => console.log('onCreate', evt.leadUuid)}
  onSubmit={(evt) => console.log('onSubmit', evt.leadUuid)}
  onOfferClick={(evt) => console.log('onOfferClick', evt.offerUuid)}
  onExit={(evt) => console.log('onExit', evt)}
  // ...other callbacks
/>

Available Events

Callback	Trigger
onInitialize	SDK finished loading the embed
onCreate	New lead created
onUpdate	Lead data updated
onNavigate	Page navigation within the flow
onSubmit	Lead form submitted
onRateTableRender	Rate table displayed with offers
onOfferClick	User clicked an offer
onErrorPageView	Error page displayed in the flow
onErrorPageRetry	User retried from the error page
onExit	User exited the SDK
onEmbedError	Web embed failed to load
onEmbedErrorRetry	User retried after embed failure

For Personal Loans, onRateTableRender populates loanOffers and specialOffers, and onOfferClick includes loan-specific fields such as financialInstitutionName, loanAmount, apr, termLength, and monthlyPayment. Every event includes a timestamp (ISO 8601 UTC).