React Native

React Native Credit Cards Integration Guide

Overview

The Engine SDK delivers the Credit Cards marketplace flow as an embedded component in your app. This page covers installation, prerequisites, the core configuration props (channel, zone, productTypes), a basic usage example, prefilling lead data, client tags, and event handlers.

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

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 Engine SDK component into any file where you want to render the Engine flow.

In v2.0+ the entry-point component was renamed from WebWrapper to EngineSDK. The props and behavior are otherwise identical — choose the tab that matches your installed version. All examples on this page are shown for both versions.

v2.0+

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

v1.x

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

Basic Example

v2.0+

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

v1.x

<WebWrapper
  channel="your-channel"
  zone="your-zone"
  productTypes={[ApiModels.ProductType.CreditCard]}
  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. ProductType is imported from the Engine SDK package — use [ApiModels.ProductType.CreditCard] for Credit Cards, which maps to the string value "credit_card".
bearerToken	string	For prefill	API token from your Partner Manager. Required to use the Prefill API. Without it, the standard non-prefilled flow renders.
style	ViewStyle	No	Style applied to the underlying view, e.g. {{ height: '100%' }}.
personalInformation, financialInformation, creditInformation, creditCardInformation	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 the Engine SDK component (e.g. personalInformation, financialInformation, creditInformation, creditCardInformation).

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

Example

v2.0+

<EngineSDK
  channel="your-channel"
  zone="your-zone"
  bearerToken="{your_token}"
  productTypes={[ApiModels.ProductType.CreditCard]}
  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',
  }}
  financialInformation={{
    annualIncome: 20000,
  }}
  creditInformation={{
    providedCreditRating: ApiModels.ProvidedCreditRating.Good,
  }}
  creditCardInformation={{
    cardPurposes: [
      ApiModels.CardPurpose.BalanceTransfer,
      ApiModels.CardPurpose.CashBack,
    ],
  }}
  onExit={(evt) => console.log('onExit', evt)}
/>

v1.x

<WebWrapper
  channel="your-channel"
  zone="your-zone"
  bearerToken="{your_token}"
  productTypes={[ApiModels.ProductType.CreditCard]}
  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',
  }}
  financialInformation={{
    annualIncome: 20000,
  }}
  creditInformation={{
    providedCreditRating: ApiModels.ProvidedCreditRating.Good,
  }}
  creditCardInformation={{
    cardPurposes: [
      ApiModels.CardPurpose.BalanceTransfer,
      ApiModels.CardPurpose.CashBack,
    ],
  }}
  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;
}

interface LeadFinancialInformation {
  annualIncome?: number; // raw integer value (e.g. 20000)
}

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

interface LeadCreditCardInformation {
  cardPurposes?: ApiModels.CardPurpose[]; // enum below
}

Enums / Accepted Values

Use a member of the corresponding ApiModels enum (each member maps to the on-the-wire value shown):

enum CardPurpose {
  BalanceTransfer = 'balance_transfer',
  CashBack = 'cash_back',
  EarningRewards = 'earning_rewards',
  ImproveCredit = 'improve_credit',
  LowInterest = 'low_interest',
  NewToCredit = 'new_to_credit',
  Student = 'student',
  TravelIncentives = 'travel_incentives',
}

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

// Access via the ApiModels namespace, e.g. ApiModels.CardPurpose.BalanceTransfer
// 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 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.

v2.0+

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

v1.x

<WebWrapper
  channel="your-channel"
  zone="your-zone"
  bearerToken="{your_token}"
  productTypes={[ApiModels.ProductType.CreditCard]}
  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 Engine SDK 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.

v2.0+

<EngineSDK
  channel="your-channel"
  zone="your-zone"
  bearerToken="{your_token}"
  productTypes={[ApiModels.ProductType.CreditCard]}
  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
/>

v1.x

<WebWrapper
  channel="your-channel"
  zone="your-zone"
  bearerToken="{your_token}"
  productTypes={[ApiModels.ProductType.CreditCard]}
  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

For Credit Cards, onRateTableRender populates creditCardOffers, and onOfferClick includes card-specific fields such as financialInstitutionBrandName, cardName, isITA, and cardNetwork.

Callback	Event Type	Trigger
onInitialize	InitializeEvent	SDK finished loading the embed
onCreate	CreateEvent	New lead created
onUpdate	UpdateEvent	Lead data updated
onNavigate	NavigateEvent	Page navigation within the flow
onSubmit	SubmitEvent	Lead form submitted
onRateTableRender	RateTableRenderEvent	Rate table displayed with offers
onOfferClick	OfferClickEvent	User clicked an offer
onErrorPageView	ErrorPageViewEvent	Error page displayed in the flow
onErrorPageRetry	ErrorPageRetryEvent	User retried from the error page
onExit	ExitEvent	User exited the SDK
onEmbedError	EmbedErrorEvent	Web embed failed to load
onEmbedErrorRetry	EmbedErrorRetryEvent	User retried after embed failure

Every event includes a timestamp (ISO 8601 UTC). All fields are optional and may be null or absent. For events that vary by product (onRateTableRender and onOfferClick), each field is tagged as Common, Loan only, or Credit Card only.

onInitialize

Fired once, when the SDK finishes loading the embedded experience for the first time.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted

onCreate

Fired when a new lead is created.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted
leadUuid	String	Unique identifier for the newly created lead
createPage	String	The page where the lead was created
editingPage	String	The page that the user is currently editing

onUpdate

Fired when existing lead data is updated.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted
leadUuid	String	Unique identifier for the lead
updatePage	String	The page where the update occurred
editingPage	Any	The page or pages that the user is currently editing. Can be a string or a list of strings

onNavigate

Fired on page navigation within the flow.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted
leadUuid	String	Unique identifier for the lead
fromPage	String	The page the user is navigating away from
toPage	String	The page the user is navigating to
editingPage	String	The page that the user is currently editing

onSubmit

Fired when the lead form is submitted.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted
leadUuid	String	Unique identifier for the submitted lead

onRateTableRender

Fired when the rate table is rendered with offers. Offer objects are passed through from the embedded experience as-is.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted (Common)
rateTableUuid	String	Unique identifier for the Engine rate table (Common)
loanOffers	List	Array of loan offers returned for the lead (Loan only)
specialOffers	List	Array of special offers returned for the lead (Loan only)
creditCardOffers	List	Array of credit card offers returned for the lead (Credit Card only)

onOfferClick

Fired when the user clicks an offer in the rate table.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted (Common)
leadUuid	String	Unique identifier for the lead (Common)
offerUuid	String	Unique identifier for the clicked offer (Common)
productType	String	Type of product (e.g. "loan") (Common)
productSubType	String	Sub-type of product (Common)
financialInstitutionName	String	Name of the lending institution (Loan only)
financialInstitutionUuid	String	Unique identifier for the lending institution (Loan only)
loanAmount	Any	Loan amount offered. Can be a number or a string (Loan only)
apr	Any	Annual percentage rate. Can be a number or a string (Loan only)
termLength	Any	Length of the loan term. Can be a number or a string (Loan only)
monthlyPayment	Any	Estimated monthly payment. Can be a number or a string (Loan only)
financialInstitutionBrandName	String	Brand name of the card issuer (Credit Card only)
cardName	String	Name of the credit card (Credit Card only)
isITA	Boolean	Whether the offer is an instant-to-apply offer (Credit Card only)
cardNetwork	String	Card network (e.g. Visa, Mastercard) (Credit Card only)

onErrorPageView

Fired when the error page is displayed within the embedded flow. This is different from onEmbedError, which fires when the embedded experience itself fails to load.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted
leadUuid	String	Unique identifier for the lead
fromPage	String	The page the user was on before the error
editingPage	String	The page that the user was editing

onErrorPageRetry

Fired when the user taps "Retry" on the error page within the embedded flow.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted
leadUuid	String	Unique identifier for the lead
toPage	String	The page the user is retrying to navigate to
editingPage	String	The page that the user was editing

onExit

Fired when the user dismisses the SDK, either by tapping "Close" on the SDK's error screen or by exiting from within the embedded flow.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted

onEmbedError

Fired when the embedded experience fails to load (network error, or an HTTP status of 400 or above). The SDK then shows an error screen with "Retry" and "Close" options.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted
errorMessage	String	Description of the error that occurred

onEmbedErrorRetry

Fired when the user taps "Retry" on the SDK's error screen after a load failure.

Field	Type	Description
timestamp	String	ISO 8601 UTC timestamp of when the event was emitted
errorMessage	String	Description of the original error that triggered the retry

Changelog

View the full React Native Credit Cards SDK changelog

2.1.1 (2026-09-29)

• Improve type definition

2.1.0 (2026-09-15)

• Made channel and zone required properties for SDK initialization.

2.0.1 (2026-08-18)

• Fixed external browser navigation to properly open links outside the app

2.0.0 (2026-08-4)

• Renamed the WebWrapper entry point to EngineSDK. Update existing imports and usage to use EngineSDK.

1.1.0 (2026-07-28)

• Upgraded build tooling to support latest React Native features and improvements

1.0.0 (2026-07-14)

• Integrated OpenAPI specifications for improved API type safety and reliability

• Added embed URL resolution to properly handle partner page prefill URL

• Added leads prefill endpoint integration

• Added error view handling

0.1.0 (2026-04-21)

• Improved type definitions

0.0.4 (11 Feb 2026)

• Initial release of the web wrapper SDK — a lightweight WebView-based wrapper for embedding web-based SDK flows in React Native apps

• Accepts channel, zone, and exp as input props

• Includes a Shimmer loading component shown while the WebView loads

• Replaced URL constructor with string/regex-based URL parsing for broader compatibility across Android versions and JS engines

• Peer dependencies for react and react-native are now explicitly declared