Finance Lend iPhone app

How to set up, build and publish the customer app for iPhone: connect it to your website, brand it, add push notifications and release it on the App Store.

FlutteriPhoneCustomer app

Getting started

Overview

The Finance Lend iPhone app is the companion of the Finance Lend SaaS website. Customers see their loans, pay instalments, upload documents and message their lender from their phone.

One app serves every lender on your platform: the customer finds their lender by name, company code or QR code, and signs in. You can also build an own-brand app for a single lender.

What is in the package

Item	What it is
`iphone_app/`	The complete Flutter project for iPhone (source code)
`iphone_app/README.md`	Setup, build, push notification and store publishing steps
`iphone_app/docs/mobile-api.md`	Reference of the customer API the app uses
`lib/`	The app code (screens, API client, session, helpers)
`ios/`	The iPhone project files

Requires the website

This app needs Finance Lend SaaS v1.7 or newer installed on an HTTPS domain. The website is sold separately.

Getting started

Features

Everything a borrower needs, in one app.

Feature	What it does
Find your lender	Search by name or city, type the company code, or scan the QR code from the lender's website. One app for many lenders.
Sign in	Email and password, or a 6-digit code sent to the customer's email, depending on what the lender allows.
Home	What is owed in total, the next payment with a Pay now button, late payments, document progress and a card for each loan.
My loans	Every loan with its status, schedule, payments, receipts and a statement.
Pay	Opens the lender's secure payment page in the phone's in-app browser.
Apply for a loan	Pick a loan type, enter the amount and term and send the request. Limits and an estimate are shown.
Documents (KYC)	Upload photos or PDFs (up to 5 MB) for each document the lender asks for and see whether each is approved, in review or not accepted.
Inbox and push	Reminders and updates in an inbox, plus phone notifications when push is set up.
Assistant	Ask questions about their own loans when the lender switches the assistant on.
Several lenders	Customers of more than one lender switch between them under More → Switch company.
Security	Fingerprint or face unlock, change password, sign out of all devices.

Not included

Owner and staff tools. Lenders manage everything on the website; the app is for customers only.
Card payments inside the app. Payment opens the lender's own gateway page.

Getting started

Requirements

Your computer (to build the app)

Flutter (a current stable release whose Dart is 3.13 or newer)
A Mac with Xcode and CocoaPods. iPhone apps cannot be built on Windows or Linux.
About 10 GB of free disk space

Phones

iPhones on iOS 15.0 or newer

Accounts

Apple Developer Program membership (yearly) to publish
Optional: a Firebase project for push notifications

Website

Finance Lend SaaS v1.7 or newer on https
The lender's website published (the company code is the name in its address, /site/<code>)
Email (SMTP) set up if you want emailed sign-in codes
The cron job running, for reminders and push

Getting started

Install Flutter & Xcode

Install FlutterFollow docs.flutter.dev for macOS and add flutter to your PATH.
Install XcodeInstall Xcode from the Mac App Store, open it once to accept the licence and install the iOS simulator. Then run sudo xcode-select --switch /Applications/Xcode.app and sudo xcodebuild -runFirstLaunch.
Install CocoaPodsRun sudo gem install cocoapods (or use Homebrew).
CheckRun flutter doctor. Flutter and Xcode should have green ticks.

Prepare the website

Do this once, before you test the app.

Use httpsThe app talks to your website over https. A debug build also accepts plain http for testing.
Publish the lender's websiteUnder Communication → Website the lender switches the website on. The company code is the name in the website address.
Open Mobile AppsThe owner's AI & Apps → Mobile Apps page shows the QR code, the company code and the page customers use to get the app. The super admin saves the store links there once the app is published.
Set up emailUnder Settings → Email SMTP. It is used for emailed sign-in codes and reminders.
Add the cron line* * * * * cd /path/to/site && php artisan schedule:run >> /dev/null 2>&1 so reminders and push messages go out.
Create a test customerAdd a customer on the website, or let one register online. The customer signs in to the app with the same email and password.

Set up the project

UnzipUnzip finance-lend-iphone-v1.0.0.zip and open the iphone_app folder in VS Code or Xcode.
Get the packagesIn that folder run flutter pub get.
Check the codeOptional: flutter analyze and flutter test.

cd iphone_app
flutter pub get

Run the app

Run on a phone or simulator

Pass your website address when you run or build, so customers never type it.

On the simulator

Start a simulator, then run:

flutter run --dart-define=API_BASE_URL=https://yourdomain.com

For a website on your own computer use your computer's network address, for example http://192.168.1.20/....

On a real iPhone

Open the projectOpen ios/Runner.xcworkspace in Xcode.
Choose your teamSelect Runner → Signing & Capabilities and pick your Apple team. Change the Bundle Identifier to your own.
RunConnect the iPhone, trust the computer, and run flutter run --dart-define=API_BASE_URL=https://yourdomain.com or press Run in Xcode.

http on iPhone

iOS only allows https:// unless you add an App Transport Security exception for testing. Use your https address or a tunnel.

Quick check without a phone

This signs in and out against your website using a customer account and reads the data the app needs:

dart run tool/smoke.dart https://yourdomain.com company-code customer@example.com password

No address given?

Leave API_BASE_URL out and the first screen also asks for the server address. That is handy while testing.

How it works

How customers connect

Way in	How it works
Search	The customer types the lender's name or city.
Company code	The customer types the code (the name in the lender's website address, `/site/<code>`).
QR code	The QR code is on the lender's Get our app page and in its website footer. Scanning it opens the app on that lender; the app asks Connect to <company> at <host>? before it trusts the address.
Link	A `financelend://connect` link, or a link from the lender's page, opens the app on that lender.

After that the sign-in screen shows the lender's logo and name, and the whole app takes on its colour. A phone can hold several lenders (More → Switch company).

An app for one lender only

Build with the lender's code as well and the app has no company screen:

flutter build ipa --dart-define=API_BASE_URL=https://yourdomain.com --dart-define=COMPANY=company-code

Fixed server

When API_BASE_URL is built in, codes and links cannot point the app to a different server.

How it works

Sign-in & security

Topic	What happens
Sign-in	Email and password, or an emailed 6-digit code when the lender allows it.
Token storage	The sign-in token is kept in the iOS Keychain, not in plain files.
Lock	Under More the customer can turn on Unlock with fingerprint or face. The app asks when it opens and after 30 seconds away. Turning it on asks once, so a lock the person cannot open is never enabled.
Password change	Changing the password signs the app out everywhere. Sign out of all devices is in the app.
First sign-in	A customer created by staff with a typed password is asked to choose their own.
Idle sign-out	An app that is not used for 90 days is signed out (`MOBILE_TOKEN_IDLE_DAYS` on the server).
Update and maintenance	The server can require a minimum app version (`MOBILE_MIN_APP_VERSION`) or show a maintenance message (`MOBILE_MAINTENANCE`).

Customise

Branding & customisation

Changes that need no new build (from the website)

The lender's logo, name and colour: the app takes them from the lender's website settings.
The QR code, company code and store links on the Mobile Apps page.
Whether emailed codes, the assistant and document pre-checks are available.

Changes in the code (then build again)

What	Where
App name shown on the phone	`Finance Lend` in `ios/Runner/Info.plist` (`CFBundleDisplayName`)
Bundle identifier	`com.financelend.finance_lend_app` — change in the Bundle Identifier in Xcode (open `ios/Runner.xcworkspace`, select Runner, then Signing & Capabilities). Do this before you publish.
Colour	`buildTheme()` in `lib/main.dart` (one seed colour)
Icon and logo	`assets/icon.png`, `assets/icon_foreground.png`, `assets/logo.png`. Replace them, then run `dart run flutter_launcher_icons`.
Version	`version` in `pubspec.yaml` (now `1.0.0+1`) and `AppConfig.appVersion` in `lib/config.dart`

Notifications

Push notifications (Firebase)

Optional. Without it the app works and the in-app inbox still fills up; only the phone pop-ups are missing.

Create a Firebase projectAt console.firebase.google.com add an iOS app with your bundle id.
Add the fileDownload GoogleService-Info.plist, put it in ios/Runner/ and add it to the Runner target in Xcode.
Add the APNs keyCreate an APNs key in your Apple developer account and upload it in Firebase (Project settings → Cloud Messaging). Turn on the Push Notifications capability in Xcode.
Connect the serverProject settings → Service accounts → generate a private key. On the server put its path in .env as FCM_CREDENTIALS=/path/key.json.
Check the schedulerThe Laravel cron line must be running.

When customers are notified

Before and after an instalment is due (daily reminders)
A payment is received
A loan is approved or rejected
A document is approved or needs attention

Release

Build the release

Set your team and idIn Xcode (Runner → Signing & Capabilities) pick your team and use your own bundle identifier.
Set the versionversion in pubspec.yaml (for example 1.0.0+1; the number after + must go up on every upload).
Build the archiveflutter build ipa --dart-define=API_BASE_URL=https://yourdomain.com
UploadUpload the result with Transporter, or open the archive in Xcode → Window → Organizer → Distribute App.

Testing first

Use TestFlight to try the build on real iPhones before you submit it for review.

Release

Publish on the App Store

Apple Developer ProgramJoin at developer.apple.com.
Create the appApp Store Connect → Apps → + → New App. Use the same bundle identifier as in Xcode.
Store pageAdd the name, subtitle, description, keywords, support URL, privacy policy URL, and screenshots for the iPhone sizes App Store Connect asks for.
App privacyAnswer the privacy questions (see below).
SubmitSelect the uploaded build, add notes for the reviewer (include a demo company code, email and password) and submit for review.
Add the link to your websiteCopy the App Store link into the website's Mobile Apps page (super admin) so the Get our app page shows the store button.

Review tip

Apple reviewers need to sign in. Give them a working demo company and customer in the review notes.

Release

Privacy & data safety

Use this when you fill in the store forms.

Permissions used

Permission text (Info.plist)	Why
Face ID	Keep loan details private (unlock)
Camera	Photograph documents the lender asks for
Photo library	Choose a photo of a document to send

Data the app handles

Data	Used for	Shared
Name, email, phone	Account and contact with the lender	Only with the customer's own lender
Loan, payment and document details	Showing loans and uploading documents	Only with the customer's own lender
Documents and photos the customer chooses	KYC checks by the lender	Only with the customer's own lender
Device push token (if push is on)	Sending notifications	Firebase Cloud Messaging

Your policy

Describe your own data practices in your privacy policy. The app has no ads and no analytics of its own.

Reference

Settings reference

ios/Runner/Info.plist

CFBundleDisplayName: the app name
The three usage descriptions above
A financelend://connect link so a scanned QR code opens the app

Xcode

Bundle Identifier and team (Signing & Capabilities)
Push Notifications capability (when you use push)
Minimum iOS version: 15.0

Reference

Code structure

Path	What it holds
`lib/main.dart`	App start, theme and routing
`lib/config.dart`	Build-time settings: `API_BASE_URL`, `COMPANY`, version
`lib/push.dart`	Push notification setup
`lib/api/api_client.dart`	Every call to the customer API
`lib/state/session.dart`	Signed-in lenders, tokens, lock
`lib/screens/`	Company, login, scan, shell (tabs), dashboard, loans, loan detail, apply, documents, notifications, assistant, more, switch company, change password, lock
`lib/util/`	Formatting, files, payment page, QR parsing
`lib/widgets/`	Shared pieces (company logo, confirm dialog)
`test/`	Unit and widget tests, and a screenshot renderer
`tool/smoke.dart`	Command-line check of the app against your website

The Android project in the other package has identical lib/ code; when you change one, make the same change in the other.

Maintenance

Updating to a new version

Back upKeep your own changes (name, id, icons, colours) somewhere safe.
ReplaceUnzip the new package and copy your changes over it.
Raise the versionIncrease version in pubspec.yaml.
Build and uploadBuild the release again and upload it to the App Store.

Update the website to the version the new app needs first.

Help

Troubleshooting & FAQ

Problem	Try this
The app cannot find my lender	Check the company code, that the lender's website is published, and that the address is https and reachable from the phone.
"Could not connect to the server"	Check `API_BASE_URL` (no trailing mistakes, https for release builds) and that the website opens in the phone's browser.
No emailed code arrives	Set up and test Settings → Email SMTP on the website, and check the spam folder.
The QR code does not open the app	Install the app first, then scan from inside the app (Scan QR on the first screen).
No push notifications	Check `GoogleService-Info.plist` is added and the APNs key is uploaded, `FCM_CREDENTIALS` is set on the server and the cron job runs.
Customer is asked to change password	They were created with a typed password. They choose their own once and carry on.
Payment page does not open	The lender must have a payment gateway switched on in the website's Settings.
Build fails after changing packages	Run `flutter clean`, `flutter pub get`, then `cd ios && pod install` and build again.

Do I need one app per lender?

No. One app serves every lender; the customer picks theirs. You can also build an own-brand app for a single lender.

Can owners and staff use the app?

No, it is for customers. Lenders and staff use the website.

Where is the data stored?

On your website's server. The app only keeps the sign-in token on the phone.

Can I change the server address without a new build?

Only if you built without API_BASE_URL. When it is built in, the app is tied to that server.

How do payments work?

The app opens the lender's own payment page in a secure in-app browser. No card details pass through the app.

Can I publish under my own name?

Yes. Change the name, id and icons, then publish with your own Apple account.

Do I need a Mac?

Yes, to build and submit the iPhone app. The Android app can be built on any computer.

Help

Support

Open a ticket at support.smartwebinfotech.com with your purchase code, the app version, what you did and what you saw.

Before you publish

Build and test the app on a real iPhone against your own website, including sign-in, a payment and a document upload. Store reviewers will do the same.