Thu tiền bot Telegram với VietQR: Hướng dẫn AgentPay

2026-07-24 · AgentPay VN

bot-telegramvietqragentpaypythonthanh-toán

Tình huống đau đớn: Bạn đang mất khách vì không thể nhận tiền

Hãy tưởng tượng: Bạn có một bot Telegram bán khoá học lập trình, với hàng trăm học viên chờ đợi. Nhưng mỗi lần ai đó muốn mua, bạn phải yêu cầu họ chuyển tiền qua tin nhắn riêng, chụp ảnh xác nhận, rồi kiểm tra thủ công trong ngân hàng... Kết quả? 30-40% khách hàng bỏ cuộc vì quá phiền phức. Tiền mất, khách mất.

Nếu bạn là nhà phát triển chatbot AI, tình cảnh còn tệ hơn: agent của bạn có khả năng bán hàng, hỗ trợ khách, nhưng bó tay không thể xử lý thanh toán vì không có cách an toàn để kết nối với hệ thống ngân hàng Việt Nam.

Có một giải pháp tuyệt vời, và đó là AgentPay VN.

AgentPay là gì? Tại sao nó khác biệt?

AgentPay VN là một SDK Python open-source (MIT License) cho phép bot Telegram, AI agent, hay bất kỳ ứng dụng nào của bạn nhận thanh toán VietQR một cách tức thì. Điểm khác biệt lớn nhất:

Không giữ tiền: Mã QR trỏ thẳng vào tài khoản ngân hàng của bạn. Không có trung gian.
Tự động xác nhận: Kết nối trực tiếp với ngân hàng để nhận thông báo thanh toán trong giây lát.
Được thiết kế cho AI: Hỗ trợ MCP (Model Context Protocol) để tích hợp ngay vào Claude, GPT hay agent khác.
Đơn giản lắm: Chỉ 3 dòng logic: tạo yêu cầu thanh toán → gửi QR → đợi settlement.

Thay vì xây dựng hệ thống thanh toán từ đầu (tốn tiền, tốn thời gian, rủi ro cao), bạn cài đặt một package và bắt đầu nhận tiền trong 5 phút.

Cài đặt AgentPay: Nhanh như chớp

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

pip install agentpay-vn

Xong. Không cần cấu hình phức tạp, không cần API key dài dòng.

Bước 2 (tuỳ chọn): Nếu bạn dùng AI agent, cài MCP server

pip install agentpay-mcp

MCP server cho phép Claude hoặc agent khác gọi AgentPay bằng tiếng tự nhiên.

Quy trình 3 bước: Thu tiền bằng VietQR

Bước 1: Tạo yêu cầu thanh toán

Khi khách hàng bảo muốn mua, bạn gọi create_payment_request():

from agentpay_vn import PaymentRequest, AgentPayClient

# Khởi tạo client
client = AgentPayClient(
    merchant_id="your_merchant_id",  # Lấy từ ngân hàng
    bank_account="123456789",         # Tài khoản nhận tiền
    bank_code="970422"                # Mã ngân hàng (VCCB, Vietcombank...)
)

# Tạo yêu cầu thanh toán
payment = client.create_payment_request(
    amount=199000,                     # 199.000 VND
    description="Khoá học Python cơ bản",
    order_id="ORDER_12345",           # ID duy nhất từ hệ thống của bạn
    customer_phone="0901234567"       # Số điện thoại khách (tuỳ chọn)
)

print(f"QR Code URL: {payment.qr_url}")
print(f"Checkout URL: {payment.checkout_url}")

Giải thích từng dòng: - merchant_id: Định danh duy nhất của bạn trong hệ thống. - create_payment_request(): Tạo một giao dịch mới, trả về object chứa QR code. - qr_url: Đường dẫn đến ảnh QR để hiển thị (hoặc embed vào bot). - checkout_url: URL để khách bấm nếu muốn thanh toán qua web (thay vì scan QR).

Bước 2: Gửi QR tới khách hàng

Dựa trên nền tảng của bạn:

Telegram bot:

import telebot
from io import BytesIO
import requests

bot = telebot.TeleBot("YOUR_BOT_TOKEN")

@bot.message_handler(commands=['buy'])
def handle_buy(message):
    user_id = message.chat.id

    # Tạo yêu cầu thanh toán
    payment = client.create_payment_request(
        amount=199000,
        description="Khoá học Python cơ bản",
        order_id=f"USER_{user_id}_ORDER_{int(time.time())}"
    )

    # Tải ảnh QR
    qr_image = requests.get(payment.qr_url).content

    # Gửi ảnh QR tới user
    bot.send_photo(
        user_id,
        BytesIO(qr_image),
        caption=f"Quét mã QR hoặc [nhấn vào đây]({payment.checkout_url}) để thanh toán 199.000 VND",
        parse_mode="Markdown"
    )

    # Lưu order_id để đợi settlement
    pending_orders[user_id] = payment.order_id

Bước 3: Đợi xác nhận thanh toán

Sau khi khách quét QR và chuyển tiền, ngân hàng sẽ gửi thông báo cho bạn (qua bank feed hoặc webhook). AgentPay xử lý tự động:

import asyncio
from agentpay_vn import await_settlement

async def wait_for_payment(order_id, user_id, timeout=900):
    """
    Đợi khách thanh toán (tối đa 15 phút)
    """
    try:
        settlement = await client.await_settlement(
            order_id=order_id,
            timeout=timeout  # Giây
        )

        if settlement.status == "confirmed":
            print(f"✓ Thanh toán thành công! {settlement.amount} VND")

            # Kích hoạt tài nguyên cho khách
            bot.send_message(
                user_id,
                f"🎉 Thanh toán thành công!\n"
                f"Access code: ABC123XYZ\n"
                f"[Vào học ngay](https://yoursite.com/course/python)",
                parse_mode="Markdown"
            )
            return True
        else:
            print(f"✗ Thanh toán thất bại: {settlement.error}")
            return False

    except asyncio.TimeoutError:
        print(f"⏱ Hết thời gian đợi. Khách chưa thanh toán.")
        bot.send_message(
            user_id,
            "Hết thời gian thanh toán. Vui lòng /buy lại để tạo mã QR mới."
        )
        return False

# Gọi trong background task
asyncio.create_task(wait_for_payment(order_id, user_id))

Tích hợp với AI Agent: MCP Configuration

Nếu bạn đang xây dựng chatbot AI có khả năng tự động bán hàng, cấu hình MCP như sau:

config.json (cho Claude Desktop hoặc hosting):

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "AGENTPAY_MERCHANT_ID": "your_merchant_id",
        "AGENTPAY_BANK_ACCOUNT": "123456789",
        "AGENTPAY_BANK_CODE": "970422"
      }
    }
  }
}

Sau khi cấu hình, Claude sẽ có khả năng: - Tạo yêu cầu thanh toán khi khách đồng ý mua - Gửi QR code hoặc link thanh toán - Kiểm tra trạng thái giao dịch - Tự động gửi access code sau khi xác nhận thanh toán

Ví dụ hội thoại AI:

Khách: "Tôi muốn mua khoá học Python của bạn"
AI: "Tuyệt vời! Khoá học này có giá 199.000 VND, bao gồm 20 bài học video + project thực tế. Tôi sẽ tạo mã QR thanh toán cho bạn."
[Gửi QR code]
AI: "Quét mã này hoặc [nhấn vào đây] để thanh toán. Tôi sẽ xác nhận trong giây lát."

[Khách thanh toán]

AI: "🎉 Thanh toán thành công! Access code của bạn là ABC123XYZ. Đăng nhập vào [khoá học] bằng code này. Chúc bạn học tập vui vẻ!"

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

Giả sử bạn là Huy, một lập trình viên dạy khoá học Python online qua Telegram. Trước khi dùng AgentPay:

Mỗi ngày nhận 5-10 yêu cầu mua khoá
Phải nhắn tin từng người, yêu cầu chuyển tiền
Sau 3-5 ngày mới xác nhận được ai đã thanh toán
Một số khách "biến mất" sau khi chuyển tiền, Huy phải kiểm tra thủ công
Conversion rate chỉ 40% vì quá phiền phức

Sau khi dùng AgentPay:

Bot tự động tạo QR và gửi ngay khi khách nói "Mua khoá Python"
Xác nhận thanh toán trong vòng 10 giây (ngân hàng mở không)
Bot tự động gửi access code khi thanh toán thành công
Không cần Huy can thiệp → Huy có thêm 3-4 giờ mỗi ngày để tạo nội dung
Conversion rate tăng lên 85% nhờ quy trình suôn sẻ
Doanh thu tăng 200% trong 3 tháng

Nên vs Không nên

Tiêu chí	✅ Nên	❌ Không nên
Loại sản phẩm	Khoá học, ebook, phần mềm, dịch vụ	Hàng vật lý cần giao (dùng kèm shipping)
Lượng giao dịch	Bắt đầu từ 1 giao dịch/ngày	Không giới hạn, chịu được hàng triệu
Cấu hình	Ghi tên người chuyển tiền vào mô tả	Để trống description (khách lú lẫn)
Timeout	900 giây (15 phút) cho sản phẩm số	60 giây cho thanh toán siêu tốc
Xử lý lỗi	Luôn wrap `await_settlement()` trong try-except	Bỏ xử lý lỗi (bot sẽ crash)
Thông báo khách	Gửi thông báo tức thì sau thanh toán	Để khách chờ và "spam" yêu cầu
Lưu trữ order	Lưu `order_id` vào database hoặc cache	Chỉ lưu trong bộ nhớ (mất khi bot restart)

Câu hỏi thường gặp (FAQ)

1. AgentPay có giữ tiền không? Có an toàn không?

Không. AgentPay hoàn toàn không giữ tiền. Mã QR được tạo sử dụng định dạng VietQR chuẩn của Ngân hàng Nhà nước, trỏ trực tiếp vào tài khoản ngân hàng của bạn. Khi khách quét mã, tiền đi thẳng vào ngân hàng của bạn mà không qua AgentPay. AgentPay chỉ giúp bạn tạo QR, theo dõi giao dịch, và xác nhận thanh toán (qua bank feed hoặc webhook). Giống như bạn tự tạo QR bằng app ngân hàng, nhưng tự động hoá.

2. Tôi cần tích hợp với ngân hàng như thế nào?

Cô cách:

Cách 1 (Khuyên dùng): Dùng bank feed tự động. AgentPay sẽ kết nối vào API ngân hàng của bạn (nếu ngân hàng hỗ trợ) để lấy danh sách giao dịch hàng ngày. Bạn chỉ cần cấp quyền một lần.

Cách 2: Setup webhook từ ngân hàng. Ngân hàng sẽ gửi thông báo mỗi khi có tiền vào. AgentPay xử lý thông báo này và đối chiếu với order_id.

Cách 3: Nếu ngân hàng của bạn không hỗ trợ API, bạn có thể dùng polling (kiểm tra định kỳ), nhưng sẽ chậm hơn.

Xem tài liệu: https://agentpay.servicesai.vn/v1/docs

3. Có phí gì không? Tại sao lại free?

AgentPay VN là open-source MIT License. Hoàn toàn free vì:

Không có trung gian giữ tiền → không cần trang web, server tốn kém
Được phát triển bởi cộng đồng
Chỉ giúp bạn tạo QR + xác nhận thanh toán (mọi thứ khác bạn tự làm)

Nhưng bạn sẽ phải trả phí cho ngân hàng nếu dùng bank feed hoặc API (thường từ 500k-2M/năm), phí đó để ngân hàng quản lý tài khoản thôi, không phải cho AgentPay.

4. Có thể dùng AgentPay cho bot Facebook, Instagram, Web không?

Có. AgentPay chỉ là SDK Python, không phụ thuộc vào Telegram. Bạn có thể dùng nó với:

Bot Discord
Bot Slack
Chatbot web (FastAPI, Flask)
AI agent (Claude, GPT, custom)
Ứng dụng desktop hoặc mobile (nếu có backend Python)

Quy trình vẫn giống: tạo QR → gửi → đợi → xác nhận.

Tóm tắt nhanh

AgentPay VN = SDK Python open-source cho phép bot/agent nhận thanh toán VietQR
Không giữ tiền: QR trỏ thẳng vào tài khoản ngân hàng của bạn
3 bước: create_payment_request() → gửi QR → await_settlement()
Cài đặt: pip install agentpay-vn
Tích hợp AI: Dùng MCP server để Claude/agent tự động bán hàng
Thực tế: Tăng conversion 40→85%, tiết kiệm 3-4 giờ/ngày
An toàn: Được xây dựng theo tiêu chuẩn VietQR của Ngân hàng Nhà nước

Bước tiếp theo: Bắt đầu ngay hôm nay

Cài đặt SDK:

pip install agentpay-vn

Đọc tài liệu chi tiết:
https://agentpay.servicesai.vn/v1/docs

Fork hoặc star project trên GitHub:
https://github.com/phuocdu/agentpay-vn

Nếu bạn gặp vấn đề:
Mở issue trên GitHub hoặc tham gia cộng đồng (forum/Discord của AgentPay nếu có).

Bạn sẽ ngạc nhiên nhất khi thấy bot của mình bắt đầu tạo doanh thu mà không cần bạn can thiệp. Từ viễn tưởng thành hiện thực chỉ trong 30 phút cài đặt.

Bắt đầu →

← Tất cả bài