Architecture
Flourish Fi sits between your core banking system and your customer's experience. You push behavioral events from your existing infrastructure; Flourish runs the mission engine; rewards flow back to you for delivery. No shared databases, no replication of customer data, no PII.
End-to-end flow
A single event — say, a card transaction at a grocery store — travels left to right through five stages.
Your stack
1. Bank / Fintech
Your core banking, your card processor, your transfer rails.
- Card authorization fires
- Bill payment settles
- Customer logs in / takes a domain action
Push
2. Events
Idempotent REST APIs. Push as events happen (or in nightly batches at Level 1).
PUT /api/v3/card-transactionsPUT /api/v3/bills/paymentsPUT /api/v3/generic-events
Flourish runs
3. Mission engine
Matches events against active missions, tracks per-user progress, triggers rewards.
- Streak / spending / per-occurrence / epic missions
- Segment-scoped rules
- Time-bounded campaigns
- Wheel and game mechanics
Webhook
4. Reward Notification
Flourish posts to your endpoint when a mission completes. You deliver the actual prize.
- Mission completion (informational)
- Cashback at cycle close (you pay)
- Eligibility check before payout
Embedded
5. SDK in your app
Native module rendered inside your existing app, branded as you. The customer never leaves your product.
- iOS, Android, React Native, Flutter, Web
- Mission progress UI
- Wheel, scratch card, trivia
- Reward redemption flows
Customer events flow left to right (you push, Flourish processes). Reward delivery flows right back (Flourish notifies, you pay). The customer-facing UI renders inside your app via the SDK — no redirect, no third-party domain.
What's required, what's optional
The minimum viable integration is small. Optional components add depth as your program matures — you can pick them up incrementally.
Inbound from you to Flourish
| Component | Required? | Notes |
|---|---|---|
| Customer code — stable anonymous user identifier | Required | Used on every event and webhook. Pick a value you can reliably reproduce per user. No PII. |
| Segment assignments — PUT/DELETE on tier or cohort segments | Required | Even single-cohort campaigns need at least one segment per qualifying user. |
| Card transaction events | If using card spend | Required for spending-threshold cashback, transaction-earned spin, onboarding activation, tiered card-spend tiers. |
| Card transaction status updates (chargebacks, reversals) | If using card spend | Drives automatic wallet reversal so reversed transactions don't pay out. |
| Bill payment events | If using bill-pay | Required for bill payment streak and on-time-payment campaigns. |
| Generic events | For custom triggers | Login, KYC completion, profile fields filled, referrals — whatever your product wants to reward beyond card and bill data. |
| Transfer events | If using remittance | First-class endpoint planned (in development). Today: push as generic events. |
Outbound from Flourish to you (webhooks)
| Component | Required? | Notes |
|---|---|---|
| Reward Notification — "this user earned a prize" | Required | This is where the integrator actually delivers the prize. Without this handler, no rewards reach customers. |
| Mission Completion — "user crossed the threshold" | Required | Informational; powers your campaign analytics and customer-support visibility. |
| Eligibility check — called before each payout | If cashback eligibility-required is on | Lets you refuse a payout from your side (KYC pending, fraud-flagged, etc.). |
| Generic Event Notification — "platform-level milestones" | Optional | Drive your CRM or analytics from platform-emitted signals. |
| Wallet Mode Switch Intent — user requested a wallet-mode change | If using Limit Booster | Only relevant for credit-card-issuer integrations running the Limit Booster feature. |
SDK
| Component | Required? | Notes |
|---|---|---|
| SDK install & init in your mobile or web app | Required | Without the SDK rendered, customers don't see the loyalty experience. iOS, Android, React Native, Flutter, Web all supported. |
| SDK theming — typography, colors, icons | Optional but recommended | Flourish ships sensible defaults; tenants who want native-feel branding configure per design system. |
| SDK event listeners — intercept user actions inside the module | Optional | Listen for redirect-out, missions clicked, etc. for navigation hooks and analytics. |
A worked example
Concretely: a customer making a 250 BRL grocery purchase, with a "spend 1,000 BRL this month, earn 30 BRL" mission active.
-
Card authorization fires at your card processor. Your core banking system records the transaction and pushes it to Flourish via
PUT /api/v3/card-transactionswithin seconds. - Flourish receives the event, looks up missions matching this customer's segment plus this event type, and finds the active spending-threshold mission.
- The mission engine increments progress: previous total 480 BRL + this transaction 250 BRL = 730 BRL of 1,000 BRL target. Not yet complete; nothing fires.
- The customer opens your app. The SDK renders the Flourish module, showing 730 / 1,000 BRL progress. The number reflects the transaction within seconds.
- Two more transactions later that month, the user crosses 1,000 BRL. The mission completes.
- Flourish posts a Mission Completion webhook to your endpoint. Your system records the completion in its analytics. No money has moved yet.
- The cashback wallet accrues 30 BRL. It sits there until the cycle closes (typically end of month).
-
At cycle close, Flourish optionally calls your eligibility endpoint. You return "eligible". Flourish then posts a Reward Notification webhook with
reward_origin: CASHBACK_WALLETand the 30 BRL amount. -
Your handler delivers the prize: deposit 30 BRL into the customer's account, return
204to Flourish, and notify the customer through your normal channels.
The same shape works for every pattern. Different events, different mission types, different prize types — same five-stage flow.
What stays in your stack
Flourish does not replace, replicate, or proxy core banking responsibilities.
Customer identity & PII
Names, emails, phone numbers, document IDs — all stay in your systems. Flourish operates on a stable customer_code that you control.
Money movement
Cashback deposits, gift card delivery, points crediting, credit-limit increases — all executed by your core banking. Flourish notifies; you move money.
Fraud & risk decisions
Final fraud judgment, KYC enforcement, AML rules — all yours. Flourish provides the levers (eligibility checks, status-driven wallet reversal); you set the policy.
Customer communication
Push notifications, email campaigns, SMS — all via your existing CRM. Flourish emits the signals (mission completed, reward earned); you decide how to surface them.
For your engineering team
Full technical contract
Endpoint schemas, webhook payloads, idempotency semantics, error codes, SDK reference, retry policy. The full developer documentation is behind a partner login — ask us for credentials.
Restricted area · partner credentials required
Want to walk through this with our team?
We can review the architecture against your stack and existing data pipelines on a 30-minute call.
Talk to our team