Technical Specification
Telegram Bot for Selling Digital Goods via Payment Gateway and Supplier API
Technologies
Python 3.11+
Aiogram 3.x
FastAPI
SQLite
Aiosqlite
Webhook for Payments
.env for Configuration
1. DATABASE
Table users:
user_id (Telegram ID)
username
balance_uah
referer_id
registration_date
Table orders:
order_id
user_id
game_username
game_user_id
quantity
price
status
created_at
Order statuses:
Pending
Queued
Queued_Deferred
Completed
Error
Cancelled
Table payments:
payment_id
user_id
amount
status
created_at
Statuses:
Table settings:
product_rate
referral_reward
2. USER PART
Main Menu
Buttons:
👤 Profile
💰 Top Up Balance
📦 Buy Product
📈 Current Rate
🛟 Support
Profile
The user is shown:
Example:
ID: 123456789
Username: XXXX_XX
Balance: 500 UAH
Invited friends: 12
Your referral link: link
3. REFERRAL SYSTEM
When following the referral link:
the bot saves referer_id.
After a successful balance top-up by the invited user:
4. BALANCE TOP-UP (RELATED TO WEBHOOK)
The user clicks:
💰 Top Up Balance
The bot asks for the amount.
The user enters the amount.
Next:
A record is created in payments.
A unique payment_id is generated.
An invoice is created via WayForPay, Monobank, etc.
The user receives a button:
Pay
After successful payment:
The payment gateway sends a webhook.
The bot verifies the digital signature.
Finds payment_id.
Checks that the payment has not been processed yet.
Changes status to success.
Credits money to balance_uah.
Credits referral bonus (if applicable).
Sends a message to the user:
"Balance successfully topped up by XX UAH."
5. BUYING PRODUCT
The user clicks:
📦 Buy Product
STEP 1
The bot asks for the quantity.
The user enters the quantity.
STEP 2
The bot calculates the cost:
cost = quantity × current rate
Shows:
Button:
Continue
STEP 3
Balance check.
If balance_uah is insufficient:
The bot offers to top up the balance.
If sufficient:
Deducts funds.
STEP 4
The bot takes Username.
STEP 5
The bot automatically fills in the entered Username in the supplier's order form.
The user only enters:
STEP 6
The bot shows the user summary information:
Nickname:
GamePass ID:
Quantity:
Cost:
Button: Confirm Order
STEP 7
After confirmation:
A record is created in orders.
Data is sent to the supplier via API.
Supplier's order_id is saved.
STEP 8
The supplier changes the order status via webhook.
Possible statuses:
Pending
Queued
Queued_Deferred
Completed
Error
Cancelled
With each status change:
With status Completed:
"Your order has been successfully completed."
With status Error or Cancelled, the user is advised to contact support
6. CURRENT RATE
Button:
📈 Current Rate
Shows the current price of one unit of the product.
Example:
1 unit = 1 UAH
Button:
Buy
7. SUPPORT
Button:
🛟 Support
Displays:
8. ADMIN PANEL
Command:
/admin
Access only for ADMIN_ID.
Statistics
Show:
Mailing
The admin enters the text.
The bot sends a message to all users.
There should be protection against FloodWait.
Change Rate
The admin enters a new rate.
The value is saved in settings.
The new rate is immediately used in all calculations.
Issue Balance
The admin enters:
The bot credits funds to balance_uah.
A log of the operation is recorded.
9. SECURITY
Verification of payment webhook signature.
Protection against double payment crediting.
Protection against reprocessing of the same order.
Verification of ADMIN_ID before opening the admin panel.
All secrets should be stored in .env.
Additional Requirements
- The code should be structured in folders
- Use of .env for configuration
- Asynchronous code
- Comments in the code
- Instructions for launching
- Ability to run on VPS Linux
From the executor, I request
- Estimated cost.
- Estimated timelines.
- Which payment systems have been integrated before.