Thu tiền bot Telegram bằng VietQR với AgentPay – Hướng dẫn chi tiết

2026-09-17 · AgentPay VN

agentpayvietqrtelegram botpythonthanh toán

Bài toán thực tế: Bạn đang gặp phải cái gì?

Hình dung một tình huống: Bạn vừa chạy một bot Telegram bán khoá học online. Mỗi ngày có 20-30 khách muốn mua, nhưng hiện tại bạn chỉ dám nhắn tin cho họ để yêu cầu chuyển khoản – vô cùng tẻ nhạt và dễ làm mất khách. Bạn cần một cách để khách quét QR ngay trong Telegram, thanh toán tự động, không phải chờ xác nhận tay. Nhưng đâu có giải pháp nào rẻ, đơn giản, không phải thuê developer hàng tháng?

Đó chính là lý do AgentPay VN tồn tại – và trong bài viết này, chúng ta sẽ đi từ 0 đến 100 để triển khai nó vào bot Telegram của bạn.

Vì sao chọn AgentPay thay vì các giải pháp khác?

Trên thị trường có nhiều cổng thanh toán Việt Nam, nhưng AgentPay có 3 điểm khác biệt quan trọng:

1. Bạn giữ toàn quyền kiểm soát: AgentPay KHÔNG bao giờ giữ tiền của bạn. Mỗi khi khách quét QR, tiền đi trực tiếp vào tài khoản ngân hàng của bạn – không cần trung gian, không cần rút tiền sau. Cổng thanh toán khác thường giữ tiền 1-3 ngày.

2. Mã nguồn mở (MIT License): Bạn có thể tải toàn bộ code, sửa đổi, triển khai trên server riêng. Không bị phụ thuộc nhà cung cấp.

3. Tích hợp AI Agent dễ dàng: AgentPay hỗ trợ MCP (Model Context Protocol) – giao thức cho phép Claude hoặc các AI agent khác gọi các hàm thanh toán một cách tự động. Ví dụ: bot AI có thể tự tạo hoá đơn, gửi QR, xác nhận thanh toán mà không cần code webhook phức tạp.

Quy trình 3 bước từ A đến Z

AgentPay hoạt động trên một nguyên tắc đơn giản:

1️⃣ create_payment_request
   ↓
2️⃣ send checkout_url (gửi link QR cho khách)
   ↓
3️⃣ await_settlement (chờ ngân hàng xác nhận thanh toán)

Mỗi bước chỉ cần 2-3 dòng code. Không cần gọi API phức tạp, không cần xử lý webhook. Đơn giản hơn bạn tưởng.

Cài đặt và thiết lập ban đầu

Bước 1: Cài đặt SDK Python

Mở terminal và chạy:

pip install agentpay-vn

Xác nhận cài đặt thành công:

python -c "import agentpay; print(agentpay.__version__)"

Bước 2: Lấy thông tin tài khoản ngân hàng

Bạn cần chuẩn bị: - Số tài khoản ngân hàng (VD: 0123456789) - Tên chủ tài khoản (VD: NGUYEN VAN A) - Mã ngân hàng (VD: VCB cho Vietcombank, ACB cho Agribank)

Danh sách mã ngân hàng tại đây.

Bước 3: Tạo file cấu hình

Tạo file agentpay_config.json:

{
  "bank_account": "0123456789",
  "account_holder": "NGUYEN VAN A",
  "bank_code": "VCB",
  "api_key": "your_api_key_here"
}

Code thực tế: Tích hợp vào bot Telegram

Ví dụ 1: Tạo yêu cầu thanh toán

from agentpay import PaymentClient
import json

# Khởi tạo client
with open('agentpay_config.json') as f:
    config = json.load(f)

client = PaymentClient(
    bank_account=config['bank_account'],
    account_holder=config['account_holder'],
    bank_code=config['bank_code']
)

# Tạo yêu cầu thanh toán
payment_request = client.create_payment_request(
    amount=199000,  # Số tiền cần thu (đơn vị: đồng)
    description="Khoá học Python nâng cao",  # Mô tả giao dịch
    order_id="ORD_20250115_001",  # ID đơn hàng duy nhất của bạn
    customer_name="Nguyễn Văn B",  # Tên khách hàng
    customer_phone="0987654321"  # SĐT khách (optional)
)

print(f"QR Code URL: {payment_request['checkout_url']}")
print(f"Request ID: {payment_request['request_id']}")

Giải thích: - amount: Số tiền tính bằng đồng, không phải ngàn đồng. 199000 = 199k VND. - order_id: Phải duy nhất mỗi lần. Bạn có thể dùng timestamp hoặc UUID. - checkout_url: Đây là link QR có thể chia sẻ qua Telegram, email, SMS.

Ví dụ 2: Chờ xác nhận thanh toán

import asyncio
from agentpay import PaymentClient

async def wait_for_payment(request_id, timeout=300):
    """
    Chờ ngân hàng xác nhận thanh toán (timeout mặc định 5 phút).
    Trả về True nếu thành công, False nếu timeout.
    """
    client = PaymentClient(
        bank_account="0123456789",
        account_holder="NGUYEN VAN A",
        bank_code="VCB"
    )

    settlement = await client.await_settlement(
        request_id=request_id,
        timeout_seconds=timeout
    )

    if settlement['status'] == 'confirmed':
        print(f"✅ Thanh toán thành công! Số tiền: {settlement['amount']} đ")
        print(f"📅 Ngày giờ: {settlement['timestamp']}")
        print(f"🏦 Tài khoản nhận: {settlement['account_number']}")
        return True
    else:
        print(f"❌ Thanh toán thất bại hoặc timeout")
        return False

# Sử dụng trong bot Telegram
asyncio.run(wait_for_payment(request_id="REQ_12345"))

Giải thích: - await_settlement() là async function – nó chờ xác nhận từ ngân hàng mà không block toàn bộ bot. - timeout=300: Chờ tối đa 5 phút. Sau đó trả về lỗi nếu chưa có tiền. - Khi tiền tới, hàm tự động trả về status confirmed kèm chi tiết giao dịch.

Kịch bản thực tế: Bot bán khoá học online

Hãy tưởng tượng bạn chạy một bot Telegram bán 3 khoá học:

Khoá học	Giá	Thời lượng
Python cơ bản	99.000đ	4 tuần
Data Science nâng cao	299.000đ	8 tuần
Full-stack Web Dev	499.000đ	12 tuần

Quy trình khi khách gõ /buy python:

from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import ContextTypes
from agentpay import PaymentClient
import json

COURSES = {
    'python': {'name': 'Python cơ bản', 'price': 99000},
    'datascience': {'name': 'Data Science nâng cao', 'price': 299000},
    'fullstack': {'name': 'Full-stack Web Dev', 'price': 499000}
}

async def handle_buy(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # Khách gõ: /buy python
    course_key = context.args[0].lower()  # 'python'

    if course_key not in COURSES:
        await update.message.reply_text("❌ Khoá học không tồn tại")
        return

    course = COURSES[course_key]
    user_id = update.effective_user.id
    user_name = update.effective_user.first_name

    # Bước 1: Tạo yêu cầu thanh toán
    with open('agentpay_config.json') as f:
        config = json.load(f)

    client = PaymentClient(
        bank_account=config['bank_account'],
        account_holder=config['account_holder'],
        bank_code=config['bank_code']
    )

    payment = client.create_payment_request(
        amount=course['price'],
        description=f"Khoá {course['name']} - Telegram {user_id}",
        order_id=f"TG_{user_id}_{course_key}_{int(time.time())}",
        customer_name=user_name
    )

    # Bước 2: Gửi link thanh toán kèm nút bấm
    keyboard = InlineKeyboardMarkup([
        [InlineKeyboardButton("💳 Thanh toán VietQR", url=payment['checkout_url'])],
        [InlineKeyboardButton("✅ Xác nhận thanh toán", callback_data=f"confirm_{payment['request_id']}")]
    ])

    await update.message.reply_text(
        f"📚 Bạn chọn: {course['name']}\n"
        f"💰 Giá: {course['price']:,}đ\n\n"
        f"Nhấn nút dưới để thanh toán qua VietQR.",
        reply_markup=keyboard
    )

    # Bước 3: Lưu request_id để xác nhận sau
    context.user_data['pending_payment'] = payment['request_id']

async def handle_payment_confirm(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # Khách nhấn nút ✅ Xác nhận thanh toán
    request_id = context.user_data.get('pending_payment')

    if not request_id:
        await update.callback_query.answer("❌ Không tìm thấy đơn hàng")
        return

    with open('agentpay_config.json') as f:
        config = json.load(f)

    client = PaymentClient(
        bank_account=config['bank_account'],
        account_holder=config['account_holder'],
        bank_code=config['bank_code']
    )

    settlement = await client.await_settlement(request_id, timeout_seconds=30)

    if settlement['status'] == 'confirmed':
        await update.callback_query.answer("✅ Thanh toán thành công!")
        await update.callback_query.message.reply_text(
            f"🎉 Chúc mừng! Bạn đã mua khoá học thành công!\n"
            f"📧 Link tài liệu sẽ được gửi trong vòng 24h.\n\n"
            f"Giao dịch: {settlement['transaction_id']}"
        )
    else:
        await update.callback_query.answer("⏳ Chưa nhận được thanh toán. Vui lòng thử lại.")

Điểm chính: - Bot không cần lưu trữ tiền ở bất kỳ đâu. - Tiền của khách đi trực tiếp vào tài khoản ngân hàng của bạn. - Bot chỉ cần chờ xác nhận từ ngân hàng (async, không block).

Cấu hình AgentPay cho AI Agent (MCP)

Nếu bạn muốn để Claude hoặc AI agent khác quản lý thanh toán tự động, bạn cần cài đặt MCP server:

pip install agentpay-mcp

Sau đó, thêm vào file Claude Config (hoặc LM Studio config):

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp.server"],
      "env": {
        "AGENTPAY_BANK_ACCOUNT": "0123456789",
        "AGENTPAY_ACCOUNT_HOLDER": "NGUYEN VAN A",
        "AGENTPAY_BANK_CODE": "VCB"
      }
    }
  }
}

Khi đó, Claude có thể tự gọi:

Agent: "Tôi sẽ tạo hoá đơn cho khách hàng Nguyễn Văn B, số tiền 199.000đ"
→ Tự động gọi create_payment_request
→ Gửi link QR
→ Chờ xác nhận
→ Gửi email hóa đơn khi thanh toán thành công

Nên & không nên khi dùng AgentPay

✅ NÊN LÀM	❌ KHÔNG NÊN LÀM
Tạo order_id duy nhất mỗi lần	Dùng cùng order_id cho 2 thanh toán
Lưu lại request_id để tra cứu	Xóa request_id sau khi tạo
Timeout 5-10 phút cho await_settlement	Timeout quá ngắn (<1 phút)
Kiểm tra settlement['status'] trước khi gửi tài liệu	Gửi tài liệu khi chỉ tạo payment chưa confirmed
Ghi log tất cả giao dịch	Không ghi log, khó debug sau
Dùng MCP nếu bạn muốn AI tự động	Cứ cần AI, nhưng cấu hình webhook phức tạp

Những câu hỏi thường gặp

❓ Tiền mất bao lâu để về tài khoản?

Trả lời: Phụ thuộc ngân hàng. Thường Vietcombank, Techcombank, Agribank mất 1-5 phút. Một số ngân hàng nhỏ hơn mất đến 30 phút. AgentPay sẽ gửi xác nhận await_settlement trong vòng thời gian đó.

❓ Có phí gì không?

Trả lời: AgentPay là mã nguồn mở hoàn toàn miễn phí (MIT License). Bạn chỉ chịu phí chuyển khoản từ khách hàng của ngân hàng (nếu khách quét QR chuyển từ ngân hàng khác). Không có phí ẩn, không có phí giao dịch.

❓ Có bắt buộc phải dùng MCP không?

Trả lời: Không. MCP chỉ cần nếu bạn muốn AI agent tự động gọi hàm thanh toán. Nếu bạn chỉ xây dựng bot Telegram thông thường, dùng SDK Python bình thường là đủ.

❓ Nếu khách chọn "Hủy" giữa chừng sao?

Trả lời: Không vấn đề gì. Nếu khách không thanh toán trong 15-30 phút, hàm await_settlement sẽ timeout và trả về status failed. Bạn có thể yêu cầu khách tạo lại hoá đơn.

Tóm tắt nhanh

🎯 AgentPay = SDK Python mã nguồn mở để nhận thanh toán VietQR trực tiếp vào tài khoản ngân hàng.
💰 Không giữ tiền: Tiền khách đi thẳng vào tài khoản của bạn, không trung gian.
⚡ 3 bước: create_payment_request → send checkout_url → await_settlement.
🤖 Hỗ trợ AI: Dùng MCP server để Claude hoặc AI agent tự động quản lý thanh toán.
📱 Dùng được ngay: Bot Telegram, web app, ứng dụng desktop – bất kỳ nơi nào có Python.
🔓 Miễn phí: Không phí giao dịch, không phí ẩn, không lock-in.
📚 Dễ tích hợp: Chỉ cần 10-20 dòng code để thêm thanh toán vào bot của bạn.

Bước tiếp theo

Cài đặt SDK: pip install agentpay-vn
Đọc tài liệu chi tiết: https://agentpay.servicesai.vn/v1/docs
Xem code ví dụ: https://github.com/phuocdu/agentpay-vn
Thử nghiệm trên môi trường test trước khi triển khai production.

Nếu bạn là người chạy bot Telegram, shop online, hoặc ứng dụng nào cần nhận thanh toán, AgentPay sẽ giúp bạn tiết kiệm 2-3 tháng lương developer. Không cần webhook phức tạp, không cần giữ tiền, chỉ cần Python và một ý tưởng tuyệt vời.

Hãy bắt đầu hôm nay! 🚀

Bắt đầu →

← Tất cả bài