📄 Developer handover & environment setup
Quick-start instructions, environment variables, DEV_MODE flags, and full design rationale are documented in this handover.
The sections below walk through each Key Feature & User Story (1.1 – 4.1). For every story you 0ll find:
Assumption: Backend task V2-36 – Backend Enhancements for User State is live, providing a user-state model (wallet address, Fiat24 KYC status) and JWT-secured endpoints. The frontend relies on this to decide which onboarding stage to display and to gate features such as IBAN availability.
User story 3.1: As a developer, I need to track TON wallet and Fiat24 KYC status in the backend.
📌 Jira / Confluence Tasks
initData already implementedUpdated onboarding carousel that leads with value and addresses user feedback. Key insight from testing: Users need to understand why Paid24/7 is different from PayPal or Revolut before they invest time in setup.
Initial loading screen users see while the app prepares their personalised onboarding experience.
<Spinner/> fades in.Copy revamped based on user testing:
📌 Jira Tasks
(planned with reference to the architecture outlined at this overview)
GET /session?initData=<tgWebAppData>
↳ { stage: "welcome" | "country" | "kyc" | "wallet" | "home",
jwt: "<short-lived token>" }Backend
telegram_idhasCountry, hasKYC, hasWallet) → returns stageFrontend
jwt → auth.setToken()router.replace('/' + stage)(Until this endpoint exists, the CTA uses a stub that always returns {stage:"welcome"}.)
| Scenario | Handling |
|---|---|
| First-time user | API returns stage:"welcome" → user stays on hero → "Create Account" leads to /country. |
| Returning, onboarding incomplete | API returns stage:"country", kyc, or wallet → hero never shown. |
| Fully onboarded | API returns stage:"home" → direct to dashboard. |
No tgWebAppData (opened outside Telegram) | Show blocking toast "Open Paid24/7 from inside Telegram"; hide CTAs. |
| JWT fail / 401 | Soft-logout to hero, toast "Session expired. Tap again." |
These screens appear when a user taps the "What can I do?" button on the welcome screen. They provide a quick tour of key capabilities before account creation.
Demonstrates the core payment functionality with emphasis on our key differentiator.
Critical feature: Recipients don't need the app or account—something users didn't initially realize but loved once they understood.
Showcases the traditional banking features alongside crypto capabilities.
Trust signal: Swiss IBAN reassures users about regulatory compliance and security.
Highlights instant spending capabilities and familiar payment methods.
User expectation: Instant, frictionless payments comparable to existing solutions they know.
Mandatory step that determines available features based on regulatory constraints. This addresses the global nature of our user base while managing compliance requirements.
Captures country of residence to tailor available features. Users from supported countries access full CHF/EUR/USD accounts with KYC and virtual cards. Unsupported countries get crypto-only features via TON wallet.
Why this matters: Fiat24's compliance requirements determine which financial services we can offer in each jurisdiction.
How to test:
Screens that appear after successful account creation, guiding users toward identity verification. User feedback: "Verify Identity" was too vague—users didn't understand what it meant or why it was needed.
Leads with immediate benefits (personal IBAN & free Mastercard) before explaining the verification requirement. Uses plain English and sets clear time expectations.
User research insight: Higher conversion when payoff is front-loaded and jargon is removed. The 5-minute promise reduces anxiety about the process.
UX detail: Both "Balances" and "Card" tabs route to verification, preventing dead-end navigation while the account is locked.
📌 Jira Tasks
Preview each possible Fiat24 KYC status returned by the API and how the app informs the user.
API reference ↗
There is one other API status COMPLETED. In this case, users are automatically routed to the next step: Activate Debit Card →
Appears for users in countries not supported by Fiat24. Shows only USDT functionality via TON wallet connection—no fiat account features.
Design decision: Removing unavailable options keeps UX clear rather than showing disabled features.
For users whose country is unsupported by Fiat24 but later change to a supported jurisdiction. Only crypto wallet features are visible until they complete Fiat24 KYC.
The actual verification process powered by Fiat24. User feedback: "What is the value of verify, why do I do this?" This flow now clearly explains the purpose and requirements upfront.
User story 2.1: As a user, I want to complete KYC for Fiat24 directly in the Mini-App without any friction.
Splitting prep across multiple pages felt like needless friction, yet a static list was too easy to skim. Tiny inline toggles create a one-tap “readiness gate”: users must actively confirm each requirement, so they pay attention without hitting extra “Next” screens. The primary button stays disabled until all items are ticked; if they tap early we nudge them by highlighting unticked rows. It’s faster for users, reduces drop-offs, and gives analytics on which prerequisite blocks people most.
Shows how the screen appears when location sharing hasn't been granted yet. Users must tap the checkbox to allow location, triggering the permission modal if denied.
Existing Fiat24 users can securely migrate their account by importing their private key, address & optional token in one step — no need to repeat identity verification. Click “Already have a Fiat24 account?” to view the guidance and input screen.
A standalone demo of the primary “Let’s confirm your identity” screen, useful for video walkthroughs and usability testing.
The core user journey from account overview through card activation. Each step builds on the previous, guiding users toward full feature unlock while demonstrating our multi-currency capabilities.
User story 4.1: As a user, I want to unlock new features step by step, reducing friction.
📌 Jira Tasks
The starting point for new users—no currency selected yet. First step in the progressive journey from overview to full activation.
Replaced single-currency CHF view with dual currency cards. Tap to switch between USDT and CHF—all buttons, balances, and feeds update instantly.
User need: Both traditional (CHF) and crypto (USDT) accounts in one app, addressing the growing demand for hybrid financial services.
Drawer explaining the 10 CHF minimum to unlock the virtual Mastercard. Auto-opens for demonstration purposes.
User expectation: Clear requirements and instant activation once threshold is met.
Shows updated messaging after user confirms they've sent the minimum deposit. Card displays "Transfer on the way..." status.
UX principle: Keep users informed about process status to reduce anxiety during waiting periods.
Final state when deposit has arrived and card is ready for use. Shows celebration messaging and clear next steps.
User goal achieved: Clear success state with immediate call-to-action to start using the card.
Normal home view post-activation. All onboarding prompts removed, showing active account with IBAN, transaction feed, and standard actions.
User experience: Clean, uncluttered interface focused on daily usage rather than setup tasks.
Non-custodial crypto wallet integration for USDT management. User feedback: Crypto veterans appreciated the non-custodial approach, while novices needed plain language explanations.
User story 1.1: As a user, I want to link my TON wallet so I can interact with crypto features.
Bottom drawer flow for connecting external TON wallets. Simulates 80% success rate to demonstrate both success and error states.
Non-custodial advantage: Users maintain control of their crypto—Paid24/7 never holds private keys.
⚠️ Known issue: Connect button sometimes requires two clicks (logged for fix).
📌 Jira Tasks
User story 1.1 (cont.): Once my wallet is linked, I want to see my address and manage USDT easily.
Post-connection home screen showing USDT mode with wallet address row. "Details ⬆" button opens drawer with address, QR code, and future MoonPay integration.
User need: Easy access to wallet information for external transfers and receiving payments.
Demonstrates send and receive functionality via bottom action buttons. Includes address validation, blockchain simulation, and sharing options.
User expectation: Familiar payment patterns (like CHF flows) applied to crypto transactions for consistency.
Accessibility and privacy controls addressing user concerns about support access and public usage. User feedback: Need for quick help access and privacy when showing the app to others.
❓ icon opens Help drawer for immediate support access. 👁 icon toggles balance visibility (blur effect) across the entire app. Balance amount itself is also tappable for quick privacy.
Privacy use case: Essential for users demonstrating the app to others or using it in public spaces.
Support access: Immediate help without leaving current screen or interrupting user flow.