Installation

Prerequisites

Before integrating the Flex Checkout React Native SDK, ensure your project meets the following requirements:

• React Native 0.76+
• iOS 15.0+
• Node.js with npm or Yarn

info

Use of this SDK is governed by our — review before integrating.

TEXT

Proprietary License

Copyright © 2026 Flexible Finance, Inc. ("Flex"). All rights reserved.

This software and its associated documentation (the "Software") are the proprietary property of Flex.

Use of this Software is strictly limited to authorized partners of Flex for the purpose of integrating Flex into their applications. Any use of this Software by an authorized partner of Flex is subject to the terms of such partner's Strategic Collaboration Agreement or other commercial agreement with Flex.

This Software may not be decompiled, disassembled, reverse-engineered, redistributed, or sublicensed without express written permission from Flex.

THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

Package Installation

Bash

yarn add @flexapp/flex-checkout-react-native@1.5.1

---

iOS Setup

After installation, run CocoaPods to link the native iOS dependency:

Bash

cd ios && pod install

---

Initializing the SDK

Initialize the Flex SDK once at app startup by calling initialize() with a FlexConfig object. The SDK is a singleton — call initialize() once, then import functions anywhere they are needed.

The recommended place is your root App component or app entry point:

JSX

import { initialize, FlexEnvironment } from '@flexapp/flex-checkout-react-native'

initialize({
  clientId: 'your-flex-client-id',
  environment: FlexEnvironment.INT, // use FlexEnvironment.PROD for production
})

warning

initialize() must be called before any checkout or button components are used.

FlexConfig Fields

Parameter	Type	Description
clientId	String	Required The client id provided by Flex which identifies your Flex client.
environment	FlexEnvironment	The environment to use — either FlexEnvironment.INT (testing) or FlexEnvironment.PROD (production). Defaults to FlexEnvironment.INT.
developer	FlexDeveloperConfig	Developer tool configuration options. Only takes effect in non-production environments.

Developer Tools

The optional developer field can be configured to enable verbose logging for debugging.

JSX

initialize({
  clientId: 'your-flex-client-id',
  developer: {
    logs: true,
  },
})

Developer Fields

Fields for the developer object.

Parameter	Type	Description
logs	Boolean	Displays informative logs for debugging the Flex React Native SDK in your console.

---

Environments

There are only two environments for you to use:

Environment	Use it for	Description
FlexEnvironment.INT	Testing	Integration / sandbox environment. Use it for all development and testing.
FlexEnvironment.PROD	Production	Production environment. Use it only for live, production traffic.

warning

INT and PROD are the only environments supported for partner integrations. Any other value on the FlexEnvironment enum is reserved for Flex-internal use and must not be used.

---

Token

loadToken takes an async function that the SDK calls to fetch a token from your backend.

JSX

import { loadToken } from '@flexapp/flex-checkout-react-native'

loadToken(async () => {
  const response = await fetch('https://your-api.com/flex-token')
  const { token } = await response.json()
  return token
})

info

On React Native, loadToken (and initialize, cleanup, logImpression, closeCheckout) are module-level functions, not methods on an SDK instance — there is no sdk.loadToken { … } form. If you're coming from the iOS or Android SDK, import each function from @flexapp/flex-checkout-react-native where you need it.

warning

loadToken must be called before checkout can be opened.

---

Lifecycle Management

User state (form input, scroll position, partial flow progress) is preserved across opens — if a user starts onboarding, closes the sheet, and reopens, they resume right where they left off.

Cleanup

Call cleanup only when the user signs out of your app. The SDK's WebView retains the previous user's in-flight UI state (form input, partial flow, cached client-side data), so if the next user signs in without cleanup, they would land into the previous user's session inside the WebView. Calling cleanup on sign-out wipes that state.

JSX

import { cleanup } from '@flexapp/flex-checkout-react-native'

function signOut() {
  cleanup()
  // ...your sign-out logic
}

After cleanup, the SDK rebuilds itself the next time the user opens checkout — you do not need to call initialize() again.

warning

Do not call cleanup from a screen's unmount handler (e.g. useEffect cleanup) or whenever the user navigates away from your checkout screen. Doing that loses the user's in-progress checkout state every time they re-enter — they'd have to restart onboarding from the beginning.

For most apps the sign-out hook is the only place cleanup is needed.

---

Analytics

logImpression(data)

Logs an impression event when the Flex checkout entry point becomes visible to the user. Call this from a useEffect or onLayout handler when the checkout entry point appears on screen.

JSX

import { logImpression } from '@flexapp/flex-checkout-react-native'

useEffect(() => {
  logImpression({
    residentId: 'xyz',
    propertyId: 'prop-12345',
    placement: 'homepage',
    element: 'split_rent_button',
  })
}, [])

Recommended fields for impression data:

Parameter	Type	Description
residentId	string	id associated with the resident.
propertyId	string	id associated with the property.
placement	'homepage' 'payments' 'checkout'	Where the user interaction takes place in your portal.
element	'split_rent_button' 'learn_more' 'awareness_banner'	Element displayed for the interaction.

---

Error Reference

Setup

initialize() throws if clientId is blank. There are no other setup-time errors; everything else surfaces via onError at runtime.

Runtime (onError messages)

The onError checkout callback receives a descriptive string whenever something goes wrong. For load failures, the SDK already displays its own retry UI inside the sheet (see Checkout → Error Handling) — these messages are for your logging and analytics.

Message	When it occurs
"No token loader provided. Call loadToken() before opening checkout."	openCheckout invoked before loadToken was registered
"FlexCheckout not configured — call Flex.initialize first."	openCheckout invoked before initialize()
"Flex checkout host not ready. Try again momentarily."	openCheckout invoked at app launch before the SDK's host has attached
"Checkout is temporarily unavailable. Please try again later."	Flex kill-switch is active for your client
"Checkout failed to load: <reason>"	WebView load, JS handshake, or token loader failed — SDK shows its own retry UI in the sheet

For "Checkout failed to load: <reason>", the <reason> suffix is one of:

• "The Internet connection appears to be offline." — no network
• "Checkout did not load in time" — 15-second JS handshake timeout
• "Failed to load token: <your loader's error>" — your loadToken function threw
• "Token loader returned an empty token" — your loadToken function returned ""

JSX

useFlexCheckout({
  onError: (error) => {
    // Log + report — the SDK already shows the user-facing error UI.
    analytics.track('flex_checkout_error', { message: error })
  },
})

---

Next Steps

Now that the SDK is installed and configured:

• Set up the Checkout modal with event callbacks
• Add the Split Rent Button component to your screen