Hướng dẫn: Cho AI agent tự thu tiền VietQR với Python

2026-08-18 · AgentPay VN

aipythonvietqrmcpagentpay

Bài Toán Thực Tế: Bot AI Của Bạn Bán Hàng Nhưng Không Thể Thu Tiền

Hãy tưởng tượng: Bạn xây dựng một con bot AI bán khoá học online. Khách hàng chat với bot, thích sản phẩm, nhưng rồi... bot "biết" khách muốn mua nhưng không biết cách lấy tiền. Phải nhờ con người can thiệp, tạo QR code thủ công, chờ xác nhận, nhập dữ liệu lại. Hiệu suất giảm 80%, khách hàng chán nản, bạn mất doanh số.

Đó là vấn đề mà AgentPay VN giải quyết: cho phép AI agent tự động tạo yêu cầu thanh toán VietQR, gửi link checkout đến khách, và tự xác nhận khi tiền về tài khoản ngân hàng thật — mà không cần agent "cầm giữ" bất kỳ đồng nào.

AgentPay VN Là Gì? Tại Sao Khác Biệt?

AgentPay VN là một SDK mã nguồn mở (MIT License) + MCP server cho Python, cho phép:

Điều quan trọng: AgentPay KHÔNG giữ tiền. QR code trỏ trực tiếp vào tài khoản ngân hàng của bạn, không có trung gian, không phí cấu, không rủi ro.

Cài Đặt: Chỉ Cần 3 Dòng Lệnh

# Cài đặt SDK Python
pip install agentpay-vn

# Nếu dùng MCP server (tích hợp Claude, Cursor)
pip install agentpay-mcp

Xong. Không cần API key từ bên thứ ba, không cần cấu hình ngân hàng phức tạp. AgentPay quản lý kết nối VietQR và ngân hàng của bạn mà bạn chỉ lo code logic kinh doanh.

Luồng Công Việc 3 Bước: Từ Khách Hàng Đến Tiền Về Tài Khoản

Bước 1: Tạo Yêu Cầu Thanh Toán

from agentpay_vn import PaymentClient

# Khởi tạo client (tự động tìm cấu hình VietQR của bạn)
client = PaymentClient()

# Tạo yêu cầu thanh toán
payment_request = client.create_payment_request(
    amount=299_000,  # Giá khoá học (đơn vị: đồng)
    description="Khoá học Python nâng cao",
    merchant_order_id="ORDER_2025_001",  # ID đơn hàng của bạn
    return_url="https://your-app.com/payment-success"
)

print(f"Checkout URL: {payment_request.checkout_url}")
print(f"Payment ID: {payment_request.payment_id}")

Giải thích dòng lệnh: - amount: Số tiền khách cần trả (đơn vị VNĐ) - description: Mô tả sản phẩm (hiển thị trong QR code) - merchant_order_id: ID đơn hàng của hệ thống bạn (dùng để tracking) - return_url: Nơi client quay lại sau khi thanh toán thành công - checkout_url: Link QR code để gửi cho khách

# Agent gửi message cho khách (qua Telegram, email, hoặc chat bot)
checkout_message = f"""
Cảm ơn bạn đã chọn khoá học!

Vui lòng thanh toán: {payment_request.amount:,} VNĐ
Link thanh toán: {payment_request.checkout_url}

Sau khi thanh toán, tài khoản của bạn sẽ được kích hoạt ngay lập tức.
"""

# Gửi message
bot.send_message(chat_id, checkout_message)

# Lưu payment_id để xác nhận sau
db.save_payment_tracking(user_id, payment_request.payment_id)

Bước 3: Chờ Xác Nhận & Tự Động Xử Lý

import asyncio
from agentpay_vn import SettlementWatcher

async def handle_payment_completion(user_id, payment_id):
    """
    Hàm này chạy sau khi khách quét QR và thanh toán.
    AgentPay tự động gọi khi ngân hàng xác nhận tiền về.
    """
    watcher = SettlementWatcher(client)

    # Chờ xác nhận thanh toán từ bank feed (timeout 15 phút)
    settlement = await watcher.await_settlement(
        payment_id=payment_id,
        timeout_seconds=900
    )

    if settlement.is_confirmed:
        # Tiền đã về tài khoản thực
        print(f"✅ Thanh toán xác nhận: {settlement.amount} VNĐ")
        print(f"   Bank reference: {settlement.transaction_ref}")

        # Tự động kích hoạt tài khoản khách
        user = db.get_user(user_id)
        user.activate_course_access()
        user.send_course_material()  # Gửi link khoá học

        # Ghi log
        db.log_transaction(
            user_id=user_id,
            amount=settlement.amount,
            status="completed",
            bank_ref=settlement.transaction_ref
        )
    else:
        # Thanh toán thất bại hoặc hết thời gian
        print(f"❌ Thanh toán không xác nhận")
        user.send_notification("Vui lòng thử lại thanh toán")

# Chạy async task
asyncio.run(handle_payment_completion("USER_123", "PAY_ABC123"))

Điểm mấu chốt: - await_settlement() không poll API liên tục (tốn resource). Nó dùng bank feed từ VietQR, xác thực trực tiếp từ ngân hàng. - Khi tiền về, hàm tự động trả về → agent xử lý bước tiếp (kích hoạt khoá học, gửi invoice, v.v.). - Nếu hết timeout, agent biết là thanh toán thất bại, có thể yêu cầu khách thử lại.

Tích Hợp Với Claude / Cursor Qua MCP Server

Nếu bạn muốn dùng Claude hoặc Cursor làm agent (thay vì tự code), hãy cấu hình MCP server:

File: .cursor/mcp.json

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"]
    }
  }
}

Hoặc cho Claude Desktop (.config/claude_desktop_config.json):

{
  "mcpServers": {
    "agentpay-vn": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "AGENTPAY_MERCHANT_ID": "your_vietqr_id"
      }
    }
  }
}

Sau đó, Claude sẽ có quyền truy cập các function: - create_payment_request(amount, description, ...) - await_settlement(payment_id) - get_transaction_history()

Kịch Bản Đời Thực: Quán Cà Phê Bán Online

Hãy xem cách một quán cà phê nhỏ ở Hà Nội dùng AgentPay:

Tình huống: Quán muốn bán gift card cà phê qua Telegram bot.

from telegram import Update
from telegram.ext import Application, CommandHandler
from agentpay_vn import PaymentClient

client = PaymentClient()

async def buy_giftcard(update: Update, context):
    """
    /buy_giftcard 500000  → Mua gift card 500k
    """
    user_id = update.message.from_user.id
    args = context.args

    if not args:
        await update.message.reply_text("Cú pháp: /buy_giftcard <số tiền>")
        return

    amount = int(args[0])

    # Tạo yêu cầu thanh toán
    payment = client.create_payment_request(
        amount=amount,
        description=f"Gift card cà phê {amount:,} VNĐ",
        merchant_order_id=f"GIFTCARD_{user_id}_{int(time.time())}"
    )

    # Gửi QR code link cho khách
    await update.message.reply_text(
        f"🎁 Gift card {amount:,} VNĐ\n\n"
        f"Quét QR này để thanh toán:\n{payment.checkout_url}\n\n"
        f"Sau khi thanh toán, bạn sẽ nhận gift card code ngay."
    )

    # Chờ xác nhận
    watcher = SettlementWatcher(client)
    settlement = await watcher.await_settlement(payment.payment_id)

    if settlement.is_confirmed:
        # Tạo gift card code
        giftcard_code = generate_giftcard_code()

        # Gửi code cho khách
        await update.message.reply_text(
            f"✅ Thanh toán thành công!\n\n"
            f"📝 Mã gift card: `{giftcard_code}`\n"
            f"Sử dụng code này khi mua cà phê tại quán."
        )

        # Lưu vào database
        db.create_giftcard(code=giftcard_code, user_id=user_id, amount=amount)

# Chạy bot
app = Application.builder().token("YOUR_TELEGRAM_BOT_TOKEN").build()
app.add_handler(CommandHandler("buy_giftcard", buy_giftcard))
app.run_polling()

Kết quả: Khách gọi /buy_giftcard 500000 → bot tạo QR code → khách quét → tiền về tài khoản quán → khách nhận gift card code tự động. Toàn bộ process không cần can thiệp con người.

So Sánh: AgentPay vs. Các Giải Pháp Khác

Tiêu Chí AgentPay VN Stripe / PayPal Momo API Webhook Thủ Công
Cài đặt pip install (2 min) Phức tạp, cần API key Phức tạp Tự code webhook
Agent tự thu tiền ✅ (native) ⚠️ (cần code kỳ diệu) ❌ ❌
Tiền nằm ở đâu Ngân hàng bạn ngay Third-party giữ (fee) Momo giữ Ngân hàng
MCP / LLM support ✅ Claude, Cursor ready ❌ ❌ ❌
VietQR native ✅ ❌ ❌ ❌
Open source ✅ MIT ❌ ❌ ❌
Khía cạnh bảo mật Bank feed (chuẩn) Webhook (yêu cầu HTTPS) Webhook + polling Tự bảo vệ

Nên & Không Nên Khi Dùng AgentPay

✅ Nên

❌ Không Nên

FAQ: Câu Hỏi Thường Gặp

Q: AgentPay có phí không? A: SDK là mã nguồn mở (miễn phí). Phí duy nhất là phí chuyển khoản của ngân hàng bạn (thường 0 nếu là chuyển nội bộ), không có phí của AgentPay.

Q: Nếu agent crash khi chờ xác nhận thanh toán thì sao? A: Bank feed được lưu trên server AgentPay. Bạn có thể dùng await_settlement() lần nữa với payment_id cũ, nó sẽ fetch lại trạng thái gần nhất. Hoặc dùng get_transaction_history() để kiểm tra toàn bộ giao dịch.

Q: Có thể dùng AgentPay cho subscription / thanh toán định kỳ không? A: Hiện tại AgentPay tập trung vào thanh toán một lần. Nhưng bạn có thể tự code logic tạo yêu cầu định kỳ (ví dụ: mỗi tháng tạo payment request mới, gửi QR cho khách).

Q: Làm sao biết khách nào đã thanh toán nếu có nhiều agent chạy cùng lúc? A: Dùng merchant_order_id (ID đơn hàng của bạn) để tracking. Mỗi agent instance có thể query lịch sử qua get_transaction_history(merchant_order_id=...) hoặc dùng database riêng lưu mapping order_id ↔ payment_id.

Q: AgentPay có hỗ trợ hoàn tiền / refund không? A: SDK cung cấp refund_payment(payment_id, amount) để tạo lệnh hoàn tiền. Tuy nhiên, hoàn tiền chỉ được xử lý nếu giao dịch gốc là chuyển khoản (không giữ tiền ở giữa), và phải được ngân hàng chấp nhận.

Tóm Tắt Nhanh: 5 Điểm Chính

Bắt Đầu Ngay Hôm Nay

Bạn đã sẵn sàng cho AI agent tự động hóa thanh toán chưa?

Cài đặt SDK:

pip install agentpay-vn

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

Fork & contribute trên GitHub: https://github.com/phuocdu/agentpay-vn

Nếu bạn xây dựng cái gì thú vị với AgentPay, hãy chia sẻ story của bạn với chúng tôi. Chúc bạn code vui! 🚀

Bắt đầu →

← Tất cả bài