01Why Telegram is a real surface for cards
Telegram has 900 million monthly active users, and a fast-growing share of those users do their financial activity inside Telegram - trading tokens, paying for bots, sending money to friends. Telegram Mini Apps are the in-chat interface for this activity, and they have become a natural place to manage financial tools.
For virtual debit cards, the use case is clear. If a user is already in Telegram checking messages, they want to manage their card without opening a separate browser. A Telegram Mini App that opens from a chat, lets them see their card, freeze it, top up, and view history - all without leaving Telegram - is a strong UX.
BitPay ships a Telegram Mini App that does exactly this. It opens from a button, renders the cabinet inside Telegram's WebView, and writes back to the cabinet backend over the WebApp SDK.
02The Telegram WebApp SDK: what cards need
Telegram Mini Apps run inside a JavaScript WebView that has access to a small SDK: window.Telegram.WebApp. Methods include: WebApp.ready(), WebApp.expand(), WebApp.close(), WebApp.sendData(), and event listeners for themeChanged, viewportChanged, backButtonClicked.
For a card interface, you do not need most of these. The Mini App loads a React (or any) component, calls the card API backend, renders the result. The Telegram SDK is used for:
- theme: respect dark or light Telegram theme by reading themeParams
- back button: handle close events so backButtonPressed closes the mini app
- mainButton: use the bottom main button for primary actions like Issue card, Freeze, etc.
- haptic feedback: trigger ImpactOccurred when cards are frozen or reissued
These are polish details, not architecture. The architecture is standard React + your card backend API.
03The backend API surface
Behind the Mini App is a backend API. The Mini App calls methods, the backend talks to the card issuer's cabinet, returns data. The minimal API surface for a card mini app is:
- POST /api/cards/issue - body: tier, monthlyLimit, dailyLimit, perTxLimit; returns cardId, maskedPan, expiry
- GET /api/cards/list - returns array of cards with status and limits
- POST /api/cards/freeze - body: cardId; returns success
- POST /api/cards/unfreeze - body: cardId; returns success
- POST /api/cards/reissue - body: cardId; returns new cardId, maskedPan, expiry
- GET /api/wallet/balance - returns USD balance
- GET /api/wallet/history?cardId=X - returns recent transactions for the card
This is the entire surface needed for a fully functional card mini app. Everything else (admin, dispute, billing) lives in the cabinet.
04Authentication inside Telegram Mini Apps
Telegram Mini Apps authenticate the user via the initData passed by Telegram. The initData contains a user object with telegram_id, first_name, and a hash signed by Telegram's bot token.
Your backend must validate the hash and use the telegram_id to identify the user. The user does not need to register separately; if the bot links to your account, the Telegram identity IS the account identity.
BitPay handles this: when a user opens the Mini App, the backend reads initData, validates the hash, finds or creates the BitPay account linked to that telegram_id, and returns the user's cards. No second login.
05The Telegram Mini App UI patterns that work
Card detail view: shows masked PAN, expiry, freeze/unfreeze button, transaction history button. Always available as the default screen when the mini app opens.
Issue card flow: tier selector (FREE/PRO/CUSTOM), optional budget hint, single confirm button. Avoid multi-step wizards - users drop off.
Top up flow: amount input, currency selector, deposit address or QR code. The Telegram SDK can trigger haptic feedback on successful copy.
History: scrollable list of transactions, filter by date or category, tap to expand details. Telegram's WebView handles infinite scroll naturally.
Avoid heavy animation, avoid modal dialogs (Telegram's WebView does not play well with them), keep everything in vertical scroll.
06Common pitfalls to avoid
Pitfall 1: Treating the Mini App as a separate product from the cabinet. The Mini App is a thin client - all state lives in the cabinet backend. If you build features in the Mini App that are not in the cabinet, you have a divergence that grows.
Pitfall 2: Storing card data in Telegram cloud storage. Telegram cloud storage is not durable for card PAN, expiry, or CVV. Store these in the cabinet backend, render only masked values in the mini app.
Pitfall 3: Ignoring the Telegram theme. Telegram has its own dark mode, light mode, and accent colors. The mini app should respect them, not override with hardcoded colors.
Pitfall 4: Building without test mode. Telegram provides test data via initData; you can simulate any user without a real Telegram account. Use it.
07The right feature ordering
If you are building a Telegram Mini App on top of a card program, ship these in order. Each is a milestone that users can test independently.
Milestone 1: card list and freeze/unfreeze. Users see their cards, can freeze any card. 80% of the value, 20% of the build.
Milestone 2: issue card flow. Users create new cards for specific workstreams.
Milestone 3: top up via QR/deposit address. Users fund their wallet from crypto.
Milestone 4: history. Users see recent transactions.
Milestone 5: temporary limit lift requests. Users request a one-shot lift for one-off large vendor charges.
Milestone 6: dispute opening. Users mark a charge as fraudulent from the history.
Do not start with milestones 4-6. The first user value is freeze and issue.
08BitPay's Telegram Mini App, in 5 minutes
BitPay ships a Telegram Mini App that wraps the cabinet. It opens from the BitPay bot in any chat, renders the user's cards, supports freeze, issue, and top up. Setup takes 5 minutes for the user.
For developers building on top of BitPay, the same backend API surface works from any client - Telegram Mini App, React web, mobile, third-party automation. The API is the contract; the client is the surface.
If you are building a Telegram Mini App that needs card functionality, the fastest path is to integrate with the BitPay backend API directly. You skip the cabinet UI, write the Telegram-native UI, and rely on the same backend for state and authorization.
