IlmFun Ecosystem & Partner Architecture
Complete technical and business guide for Payment Service Providers (PSPs), Educational Sponsors, Store Merchants, Academy Owners, and Developers building on IlmFun.
Academies & Live Classrooms
Teachers and academy owners host interactive live classes, sell purchasable academy roles, and run Academy Shops with customizable commission splits.
Unified Emerald Economy
Whole-integer Emeralds (Zumrad) power IlmFun MAX memberships, paid live lessons, role badges, and digital/physical commerce with 30-day rolling FIFO escrow.
Partner Network & APIs
Payment providers, course creators, and brands integrate via M2M REST APIs (`ifp_` keys) to process top-ups, sell store items with webhooks, and sponsor Quests.
Official Platform Endpoints & Services
All official IlmFun services communicate over TLS 1.3+ with strict role separation.
| Domain / Base URL | Role & Target Audience | Authentication |
|---|---|---|
https://ilmfun.com |
Learner & Teacher Web Portal, Account Settings, Emerald Wallet (`/account`) | User Session Cookie |
https://partner.ilmfun.com |
Official Partner Portal: Onboarding, Reserve Float, Quests Manager, Storefront & Orders | Partner Session Cookie (`ilmfun_partner_session`) |
https://partner.ilmfun.com/api/v1 |
Machine-to-Machine (M2M) Partner REST API (Payments, Shop, Webhooks, Quests) | Authorization: Bearer ifp_... |
https://docs.ilmfun.com |
Official Documentation, OpenAPI 3.0 Spec, Webhook HMAC Tester & Integration Guides | Public (`GET`) |
Emerald Economy, IlmFun MAX & Escrow Rules
How value flows safely between Learners, Teachers, Academy Owners, and Commercial Partners while maintaining 100% reserve backing and store compliance.
1. IlmFun MAX Membership (`100 💎 / 30 Days`)
IlmFun MAX is the platform's flagship individual learner/creator membership, purchased exclusively with Emeralds (`100 💎` per 30-day cycle) or redeemed via official Shop passes (`ilmfun_max_1m`, `ilmfun_max_3m`, `ilmfun_max_12m`).
⚡ Core Member Perks
• 500 MB File Uploads (10x standard 50 MB limit)
• 1080p / 1440p / 4K at 60 FPS Ultra-HD Screen Sharing
• Evolving MAX Streak Badges (`0m`, `1m`, `3m`, `6m`, `12m+`)
• Cross-Academy Custom Emojis & Priority Profile Styling
🛡️ Renewal & 7-Day Grace Protection
• Automatic renewal every 30 days if `auto_renew` is enabled and balance $\ge 100$ 💎.
• If balance is insufficient at expiration, a 7-day grace period preserves the member's streak while they complete Quests or top up.
2. Academy Monetization: Live Events, Paid Roles & Academy Shop
Academy Owners and Teachers have three built-in monetization engines inside every Academy:
| Monetization Feature | How It Works | Settlement & Protection |
|---|---|---|
| Paid Live Classes & Events | Teachers schedule live interactive lessons with an Emerald ticket price (`price_emeralds`). | 7-Day Student Refund Window (with instructor appeal right) + 30-Day Rolling FIFO Escrow. |
| Purchasable Academy Roles | Academy Owners mark custom roles as purchasable (`one_time` or `monthly` subscription in 💎). | Instant role assignment; revenue enters the Academy's 30-day clearance pipeline. |
| Academy Shop & Commission Split | Authorized members (`manageShop` permission) sell study materials, kits, or mentoring in the Academy Shop. | Academy Owner sets a `0%–50%` Academy Commission (`shop_commission_percent`); Seller receives net Emeralds and Academy Owner receives the commission. |
3. 100% Reserve-Backed Partner Loop
No unbacked Emeralds can ever be minted by third parties:
🎯 Quest Budget Escrow
When a Partner launches a Quest (`reward_emeralds * max_completions`), the full campaign budget is atomically deducted/escrowed from the Partner's available balance or Reserve Float. Deleting or reducing a quest refunds unspent Emeralds automatically.
🛍️ Partner Shop Revenue
When a learner buys a Partner Shop item (`scope = "partner"`), the net Emerald proceeds are credited directly to the Partner's account balance upon fulfillment (and reversed on refund), ready to fund Quests or settle via a Payment Provider.
Authentication, API Keys & Idempotency
Generate scoped `ifp_` machine keys in the Partner Portal and authenticate server-to-server requests over HTTPS.
1. Bearer Token Format
Include your 68-character secret key (`ifp_` prefix + 64 hex bytes) in the `Authorization` header. Keys are hashed with SHA-256 at rest and expire after 90 days.
curl -X GET "https://partner.ilmfun.com/api/v1/account" \
-H "Authorization: Bearer ifp_YOUR_64_CHAR_HEX_SECRET" \
-H "Accept: application/json"2. Permission Scopes Matrix
| Scope | Permitted Endpoints | Recommended Use Case |
|---|---|---|
read | GET /account, GET /orders, GET /shop/*, GET /quests | Accounting, reconciliation & read-only dashboards |
lookup | GET /users/{username} | Pre-checkout customer verification |
topup | POST /topups, POST /orders/{id} (top-up orders) | Payment gateway Emerald top-up invoicing |
withdrawal | POST /orders/{id} (withdrawal orders) | Automated payout execution |
refund | POST /orders/{id} (refund orders) | Unused top-up refund processing |
shop | POST/PUT/DELETE /shop/items*, POST /shop/orders/{id}/fulfill | Automated e-commerce catalog & order fulfillment |
quests | POST/PUT/DELETE /quests*, GET /quests/{id}/completions | Sponsored quest campaign management |
3. Idempotency & Snowflake IDs
Always send a unique `Idempotency-Key` (`8–128` chars) when creating top-up orders (`POST /topups`). Treat all `user_id` and `order.id` values as strings.
Idempotency-Key: inv_20261029_9f8e7d6c5b4aPayments, Top-ups, Withdrawals & Reserve Float
Integrate regional payment gateways, commercial banks, and authorized merchants with atomic reserve locking and dual-supervisor funding verification.
1. Step-by-Step Top-Up Lifecycle
Verify that the learner exists and is eligible (`payment_ready: true`) before accepting payment.
Reserves `amount` Emeralds from your `available` float into `customer_liability` and creates an `authorized` order.
{
"username": "student_ali",
"amount": 250,
"fiat_minor": 25000000,
"currency": "UZS",
"external_reference": "PSP-TX-994812"
}Transition order state: first `claim` (`authorized -> processing`), then `complete` (`processing -> completed`) once payment is confirmed, or `cancel` to release held float.
// Step A: Claim before capturing funds
{ "action": "claim", "verification_reference": "CAPTURE-8821" }
// Step B: Complete and credit Emeralds to the user
{ "action": "complete", "reference": "RECEIPT-8821", "fiat_minor": 25000000, "currency": "UZS" }2. Order State Machine Reference
| Order Kind | Current Status | Action | Next Status | Ledger Effect |
|---|---|---|---|---|
topup | authorized | claim | processing | Locks order against concurrent workers (HTTP 409 on duplicate claim). |
topup | processing | complete | completed | Consumes `customer_liability` and credits `amount` 💎 to user's spendable wallet. |
topup | authorized / processing | cancel | cancelled | Releases `customer_liability` back to provider's `available` float. |
withdrawal | authorized | claim | processing | Locks customer cashout request before bank/card disbursement. |
withdrawal | processing | complete | reported_paid | Records payout receipt; once user confirms receipt (or supervisor resolves), provider `available` float increases by `amount` 💎. |
withdrawal | authorized / processing | fail / cancel | failed_review / cancelled | Refunds held Emeralds back to the user's withdrawable balance. |
Partner Shop & Storefront API
List vouchers, courses, books, hardware kits, and automated services in the IlmFun Shop, manage inventory, and fulfill customer orders via Portal or REST API.
1. Create & Manage Shop Items
{
"category": "voucher",
"title": "IELTS Mock Exam Full Pass",
"description": "Includes Speaking, Writing, Reading & Listening with examiner feedback.",
"price_emeralds": 350,
"delivery_type": "instant",
"service_type": "webhook_custom",
"webhook_url": "https://api.partner.uz/ilmfun/shop-webhook",
"webhook_secret": "whsec_9a8b7c6d5e4f3a2b1c",
"stock": 100,
"max_per_user": 2,
"requires_contact": true
}Fulfill a manual order, attach a voucher code/tracking note, or issue a full Emerald refund (`"status": "refunded"`).
{
"status": "fulfilled",
"delivery_content": "IELTS-PASS-2026-88412",
"fulfillment_note": "Sent exam booking link to your Telegram"
}Purchase Webhooks & HMAC-SHA256 Verifier
Receive instant HTTP POST notifications when a learner buys your Shop item, verify the `X-IlmFun-Signature` header, and return dynamic license/voucher codes synchronously.
1. Webhook Request Payload & Headers
POST /ilmfun/shop-webhook HTTP/1.1
Host: api.yourcompany.uz
Content-Type: application/json
X-IlmFun-Event: shop.order.created
X-IlmFun-Order-ID: ord_shop_17301928319201
X-IlmFun-Signature: sha256=6f5e4d3c2b1a...
{
"event": "shop.order.created",
"order_id": "ord_shop_17301928319201",
"item_id": "item_partner_1730100001",
"item_title": "IELTS Mock Exam Full Pass",
"service_type": "webhook_custom",
"price_emeralds": 350,
"quantity": 1,
"buyer": {
"user_id": 1049281729,
"username": "student_ali",
"display_name": "Ali Valiyev",
"contact": "@student_ali",
"note": "Morning slot preferred"
},
"timestamp": "2026-10-29T10:15:30Z"
}2. Interactive HMAC-SHA256 Signature Calculator
Test your webhook signature verification logic right here in the browser.
Sponsored Quests & Verification API
Launch Emerald-backed Quests to grow your Telegram channel, showcase educational videos, drive website visits, or onboard students into your Academy.
1. Supported Quest Types & Verification Mechanics
| Quest Type | Required Fields | Automated Verification Mechanism |
|---|---|---|
telegram_join |
telegram_channel_id, telegram_invite_url |
Learner links their Telegram account via @ilmfunbot; IlmFun calls Telegram Bot API getChatMember in real time to verify active membership. |
video_watch |
target_url, required_seconds (5–300s) |
Server-side signed session token (POST /api/v1/quests/{id}/start) enforces minimum elapsed watch duration before verification succeeds. |
web_visit |
target_url, required_seconds (5–120s) |
Server-side timed session token verifies that the learner visited the target URL for at least required_seconds. |
academy_join |
academy_id |
Queries the IlmFun core database to confirm the learner is an active member of the target Academy. |
2. Create a Sponsored Quest via API
Escrows `reward_emeralds * max_completions` from your available Partner Balance / Reserve Float and publishes the quest immediately.
{
"title": "Subscribe to Official Partner Telegram Channel",
"description": "Join our Telegram channel for daily IELTS tips and scholarship announcements.",
"type": "telegram_join",
"reward_emeralds": 25,
"max_completions": 200,
"frequency": "once",
"telegram_channel_id": "@your_channel",
"telegram_invite_url": "https://t.me/your_channel"
}Production Code Examples
Ready-to-use snippets for cURL, Go, Node.js, Python, and PHP covering Top-up creation and Webhook HMAC-SHA256 verification.
OpenAPI 3.0.3 Endpoint Reference
Live-rendered from /openapi.json. Filter endpoints or download the specification for Postman, Insomnia, or OpenAPI code generators.