Thu tiền từ bot Telegram với VietQR và AgentPay

2026-08-26 · AgentPay VN

agentpayvietqrpythontelegramai-agents

Bài toán thực tế: Bot bán hàng của bạn đang thua lỗ vì không thể thu tiền

Bạn vừa xây dựng một bot Telegram bán khoá học tiếng Anh online. Mỗi ngày có 15-20 khách hỏi, nhưng khi họ muốn thanh toán, bạn bị kẹt. Gửi tài khoản ngân hàng để chuyển khoản? Quá chậm, không professional, và khách hay "quên". Dùng payment gateway quốc tế? Phí 3-5%, chưa kể thủ tục rắc rối. Bạn cần cách nhanh, đơn giản, an toàn để bot tự động yêu cầu thanh toán và xác nhận ngay lập tức—tất cả trong Telegram.

Đây chính là lúc AgentPay VN ra tay giúp bạn.

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

AgentPay VN là một bộ công cụ mã nguồn mở (giấy phép MIT) được thiết kế riêng cho các AI agent và bot muốn thu tiền từ khách Việt Nam qua VietQR. Điểm đặc biệt:

Không giữ tiền: Mã QR trỏ trực tiếp vào tài khoản ngân hàng của bạn, không qua trung gian nào cả.
Xác nhận tự động: Nhận feed từ ngân hàng (thông qua API) → xác nhận thanh toán trong vài giây.
Python SDK + MCP server: Dễ tích hợp với bot Telegram, Claude, hoặc bất kỳ AI agent nào.
Miễn phí: Mã nguồn mở, bạn chỉ trả phí chuyển khoản ngân hàng thông thường (0-3K VND/lần tùy ngân hàng).

Quy trình thanh toán 3 bước đơn giản

AgentPay hoạt động theo sơ đồ này:

Bot tạo yêu cầu thanh toán
         ↓
Khách quét QR VietQR
         ↓
Tiền chuyển vào TK ngân hàng của bạn
         ↓
AgentPay nhận thông báo từ ngân hàng
         ↓
Bot gửi khoá học/hàng hóa cho khách

Cả quá trình diễn ra trong 30-60 giây, khách không cần rời Telegram.

Cài đặt AgentPay SDK cho Python

Bước đầu tiên, cài đặt package từ PyPI:

pip install agentpay-vn

Nếu bạn muốn sử dụng AgentPay qua MCP server (để kết nối với Claude hoặc các AI agent khác):

pip install agentpay-mcp

Verify cài đặt:

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

Viết code cho bot Telegram: Quy trình thanh toán

Dưới đây là một ví dụ hoàn chỉnh—bot bán khoá học tiếng Anh:

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

from agentpay import PaymentRequest, create_payment_request
import asyncio

# Thông tin sản phẩm
PRODUCT_NAME = "Khoá học Tiếng Anh giao tiếp - 10 buổi"
PRICE = 500000  # VND
MERCHANT_ACCOUNT = "1234567890"  # số tài khoản ngân hàng bạn
MERCHANT_BANK = "TCB"  # Techcombank, hoặc "VIB", "MB", "ACB" v.v.

# Tạo yêu cầu thanh toán
payment_req = create_payment_request(
    amount=PRICE,
    description=f"Thanh toán {PRODUCT_NAME}",
    order_id="ORDER_20250128_001",  # ID đơn hàng duy nhất
    merchant_account=MERCHANT_ACCOUNT,
    merchant_bank=MERCHANT_BANK,
    customer_name="Nguyễn Văn A",  # Lấy từ Telegram user
    customer_phone="0987654321"      # Lấy từ Telegram user
)

print(f"QR Code URL: {payment_req.checkout_url}")
print(f"Payment ID: {payment_req.id}")

Giải thích từng dòng: - create_payment_request(): Hàm chính tạo yêu cầu thanh toán, trả về object có chứa checkout_url (link QR VietQR) và id (định danh duy nhất để tracking). - order_id: Phải unique để AgentPay tracking. Bạn có thể dùng f"{user_id}_{int(time.time())}". - merchant_account + merchant_bank: Tài khoản + ngân hàng của bạn (người bán), không phải khách hàng.

Bước 2: Gửi link QR cho khách trong Telegram

from telegram import Bot, InputMediaPhoto
import asyncio

TELEGRAM_BOT_TOKEN = "YOUR_BOT_TOKEN_HERE"
bot = Bot(token=TELEGRAM_BOT_TOKEN)

async def send_payment_to_customer(chat_id, payment_req):
    """
    Gửi mã QR thanh toán cho khách qua Telegram.
    """
    message_text = f"""
🛒 **Đơn hàng của bạn:**
{PRODUCT_NAME}

💰 **Giá:** {PRICE:,} VND

📲 **Hướng dẫn thanh toán:**
1. Bấm nút "Thanh toán" bên dưới
2. Mở ứng dụng ngân hàng
3. Quét mã QR
4. Xác nhận thanh toán

⏱️ Bạn có **15 phút** để thanh toán.
    """

    # Gửi mã QR dưới dạng ảnh hoặc link
    await bot.send_message(
        chat_id=chat_id,
        text=message_text,
        reply_markup={
            "inline_keyboard": [
                [
                    {
                        "text": "💳 Thanh toán ngay",
                        "url": payment_req.checkout_url
                    }
                ]
            ]
        }
    )

# Gọi hàm
# await send_payment_to_customer(chat_id=123456789, payment_req=payment_req)

Bước 3: Chờ xác nhận thanh toán

from agentpay import await_settlement
import asyncio

async def wait_for_payment(payment_id, timeout_seconds=900):
    """
    Chờ tiền về tài khoản.
    """
    try:
        result = await await_settlement(
            payment_id=payment_id,
            timeout=timeout_seconds,  # 15 phút
            poll_interval=5  # Kiểm tra mỗi 5 giây
        )

        if result.success:
            print(f"✅ Thanh toán thành công!")
            print(f"   Số tiền: {result.amount:,} VND")
            print(f"   Thời gian: {result.timestamp}")
            return True
        else:
            print(f"❌ Thanh toán thất bại: {result.error_message}")
            return False

    except asyncio.TimeoutError:
        print("⏱️ Hết thời gian chờ (khách chưa thanh toán)")
        return False

# Sử dụng trong handler Telegram
async def handle_buy_course(update, context):
    chat_id = update.effective_chat.id
    user = update.effective_user

    # Bước 1: Tạo yêu cầu thanh toán
    payment_req = create_payment_request(
        amount=PRICE,
        description=PRODUCT_NAME,
        order_id=f"ORDER_{chat_id}_{int(time.time())}",
        merchant_account=MERCHANT_ACCOUNT,
        merchant_bank=MERCHANT_BANK,
        customer_name=user.first_name,
        customer_phone=user.phone_number or "unknown"
    )

    # Bước 2: Gửi QR
    await send_payment_to_customer(chat_id, payment_req)

    # Bước 3: Chờ thanh toán
    is_paid = await wait_for_payment(payment_req.id)

    if is_paid:
        # Gửi khoá học cho khách
        await bot.send_message(
            chat_id=chat_id,
            text="🎉 Thanh toán thành công! Khoá học của bạn đã sẵn sàng.\n\n" +
                 "📚 Truy cập: https://course.example.com/access?token=XXX"
        )
    else:
        await bot.send_message(
            chat_id=chat_id,
            text="Thanh toán bị hủy hoặc hết hạn. Vui lòng thử lại."
        )

Cấu hình AgentPay MCP cho Claude

Nếu bạn muốn sử dụng AgentPay qua Claude (AI agent), hãy thêm cấu hình này vào claude_desktop_config.json:

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "AGENTPAY_MERCHANT_ACCOUNT": "1234567890",
        "AGENTPAY_MERCHANT_BANK": "TCB",
        "AGENTPAY_API_KEY": "your_api_key_if_needed"
      }
    }
  }
}

Sau đó, Claude có thể gọi trực tiếp AgentPay để tạo yêu cầu thanh toán mà không cần code trung gian.

Ví dụ kịch bản thực tế: Quán cà phê bán online

Quán cà phê "Cà Phê Sáng" muốn bán cà phê qua Telegram, khách đặt hàng và thanh toán trực tiếp:

Quy trình: 1. Khách: /order → chọn "Cà phê đen đá (30K)" 2. Bot: Tạo yêu cầu thanh toán, gửi QR VietQR 3. Khách: Quét QR, chuyển 30K 4. Bot: Nhận thông báo từ ngân hàng → xác nhận 5. Bot: Gửi voucher pickup, in đơn hàng cho quán

Code snippet:

MENU = {
    "1": {"name": "Cà phê đen đá", "price": 30000},
    "2": {"name": "Cà phê sữa nóng", "price": 35000},
    "3": {"name": "Trà dâu tây", "price": 25000},
}

async def order_coffee(update, context):
    choice = update.message.text  # "1", "2", hoặc "3"
    item = MENU.get(choice)

    if not item:
        await update.message.reply_text("Lựa chọn không hợp lệ")
        return

    payment_req = create_payment_request(
        amount=item["price"],
        description=f"Đơn hàng: {item['name']}",
        order_id=f"CAFE_{update.effective_user.id}_{int(time.time())}",
        merchant_account=MERCHANT_ACCOUNT,
        merchant_bank=MERCHANT_BANK,
        customer_name=update.effective_user.first_name
    )

    await update.message.reply_text(
        f"☕ {item['name']} - {item['price']:,} VND\n" +
        f"Bấm để thanh toán: {payment_req.checkout_url}"
    )

    if await wait_for_payment(payment_req.id):
        voucher_code = f"PICKUP_{payment_req.id[:8]}"
        await update.message.reply_text(
            f"✅ Thanh toán thành công!\n" +
            f"📍 Mã lấy hàng: {voucher_code}\n" +
            f"⏱️ Hàng sẽ sẵn sàng trong 10 phút"
        )

Nên làm gì & Không nên làm gì

✅ Nên	❌ Không nên
Lưu `order_id` để tracking đơn hàng	Để timeout = 0 (khách không có thời gian thanh toán)
Kiểm tra `payment_req.success` trước khi gửi hàng	Gửi hàng khi chưa xác nhận tiền
Dùng unique `order_id` cho mỗi giao dịch	Tái sử dụng `order_id`
Ghi log tất cả thanh toán để audit	Tin tưởng callback mà không verify
Gửi xác nhận chi tiết cho khách	Chỉ gửi "OK" mà không có voucher/thông tin
Cấu hình timeout hợp lý (10-15 phút)	Set timeout quá lâu (>1 giờ)

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

Q: Tiền sẽ về TK ngân hàng mất bao lâu? A: Nếu dùng VietQR (chuyển khoản trong nội bộ ngân hàng), tiền về trong 1-3 phút. Nếu khách chuyển từ ngân hàng khác, mất 1-2 giờ. AgentPay không giữ tiền, nó chỉ nhận thông báo từ ngân hàng của bạn.

Q: Phí là bao nhiêu? A: AgentPay miễn phí. Bạn chỉ trả phí chuyển khoản thông thường của ngân hàng (thường 0-3K/lần). VietQR còn miễn phí chuyển khoản nội bộ.

Q: Có cần API key hay tài khoản nào không? A: Không. AgentPay tạo QR VietQR dựa trên số tài khoản + ngân hàng của bạn. Chỉ cần cấu hình 1 lần là xong.

Q: Khách có thể "lừa" và không thanh toán được không? A: Không. Vì mã QR trỏ trực tiếp vào TK ngân hàng của bạn (thông qua VietQR), khách phải thanh toán để tiền xuất hiện. AgentPay chỉ xác nhận khi tiền thực sự về.

Q: Có hỗ trợ nhiều tài khoản ngân hàng không? A: Có. Bạn có thể tạo nhiều instance của PaymentRequest với merchant_account + merchant_bank khác nhau. Ví dụ: TK chính dùng cho hóa đơn lớn, TK phụ cho tip/donate.

Tóm tắt nhanh

AgentPay VN là SDK Python mã nguồn mở để bot/AI agent thu tiền VietQR mà không giữ tiền.
Cài đặt: pip install agentpay-vn
3 bước thanh toán: create_payment_request() → gửi link QR → await_settlement()
Tiền về TK ngân hàng: 1-3 phút (nội bộ), 1-2 giờ (liên ngân hàng), miễn phí AgentPay.
Hỗ trợ Telegram, Claude, MCP server, dễ tích hợp vào bot/AI agent bất kỳ.
Ví dụ thực tế: Bán khoá học, cà phê, bất cứ dịch vụ nào online.

Bước tiếp theo

✨ Sẵn sàng thử AgentPay chưa?

Cài đặt ngay: pip install agentpay-vn
Xem tài liệu chi tiết: https://agentpay.servicesai.vn/v1/docs
Xem code trên GitHub: https://github.com/phuocdu/agentpay-vn
Thử ví dụ Telegram: Fork repo, thay MERCHANT_ACCOUNT + MERCHANT_BANK, chạy bot của bạn.

Dùng AgentPay, bạn không chỉ tiết kiệm phí, mà còn giảm thời gian xác nhận từ hàng phút xuống vài giây. Bot của bạn sẽ tự động gửi hàng/dịch vụ ngay khi tiền về—trải nghiệm khách hàng không thể tốt hơn! 🚀

Bắt đầu →

← Tất cả bài