Thêm thanh toán VietQR vào AI Agent chỉ trong 10 phút

2026-09-30 · AgentPay VN

aipythonvietqrmcpthanh toán

Bạn có bot AI nhưng không thể kiếm tiền từ nó?

Hình ảnh này chắc quen thuộc: bạn xây dựng một chatbot bán khoá học, hoặc một AI agent tự động xử lý đơn hàng cho quán cà phê của mình, nhưng khi khách hàng muốn thanh toán, bạn phải dừng bot lại, chuyển qua PayPal hay Stripe (mất phí cao, còn phải verify), hoặc ghi nhớ thanh toán thủ công. Chuyện này làm mất đi toàn bộ sự tự động hóa mà bạn vốn muốn đạt được.

Hôm nay mình sẽ giới thiệu cách để bot của bạn tự xử lý thanh toán trực tiếp vào tài khoản ngân hàng của bạn trong Python, chỉ cần 3 dòng code chính.

Vấn đề: Tại sao tích hợp thanh toán lại khó vậy?

Hầu hết các giải pháp thanh toán hiện tại đều có những hạn chế:

PayPal/Stripe: Phí giao dịch 2-3.6%, quá cao cho những giao dịch nhỏ
Momo/Zalopay: Cần đăng ký merchant, xử lý phức tạp, giấy tờ dài
Direct bank: Không có API, phải làm thủ công
Tích hợp vào AI agent: Hầu hết SDK thanh toán không được thiết kế cho agent (không có MCP support)

Vậy nên khi bạn muốn bot AI của mình có khả năng thanh toán, bạn phải:

Tìm giải pháp thanh toán riêng
Học API của nó (có thể phức tạp)
Tạo wrapper để bot hiểu được
Xử lý lỗi, retry, confirmation
Đợi tiền về tài khoản

Tất cả cộng lại, dễ dàng mất 2-3 ngày.

Giải pháp: AgentPay VN

AgentPay VN là một Python SDK open-source (MIT License) + MCP server cho phép AI agent của bạn thu VietQR payment trực tiếp vào tài khoản ngân hàng mà không cần đứng giữa tiền.

Đặc điểm chính:

MIT License: Sử dụng miễn phí, sửa đổi được
Open-source: Code công khai, có thể tự host
Zero-hold: Tiền chuyển trực tiếp vào ngân hàng bạn, không giữ lại
Bank confirmation: Tự động xác nhận khi tiền về tài khoản
Agent-ready: Có MCP support, dùng trực tiếp với Claude, GPT hay agent framework nào

Ba bước cơ bản

create_payment_request() → send checkout_url → await_settlement()

Chỉ thế thôi. Không cần webhooks phức tạp, không cần polling database, không cần xử lý callback.

Cài đặt AgentPay VN trong 2 phút

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

pip install agentpay-vn

Đó là tất cả. Không cần dependency khác.

Bước 2: Khởi tạo client

from agentpay_vn import AgentPayClient

# Khởi tạo client (có thể dùng local hoặc remote MCP server)
client = AgentPayClient(
    base_url="http://localhost:8000",  # Nếu self-host
    # hoặc dùng public instance nếu có
)

Bước 3: Tạo payment request

# Tạo yêu cầu thanh toán
payment = await client.create_payment_request(
    amount=150000,  # 150,000 VND
    description="Khoá học Python Advanced",
    order_id="order_12345",  # ID đơn hàng của bạn
    merchant_account="1234567890",  # STK người bán (VietQR)
)

print(f"Checkout URL: {payment.checkout_url}")
# Gửi checkout_url cho khách

Hướng dẫn thực tế: Bot bán khoá học

Giả sử bạn có một Telegram bot hoặc chatbot web bán khoá học Python. Dưới đây là flow đầy đủ:

Kịch bản

Khách: "Tôi muốn mua khoá học Advanced"
Bot: "Giá là 150,000 VND. Tôi sẽ tạo QR code cho bạn."
Bot tạo payment request → bot gửi QR code cho khách
Khách quét QR → chuyển 150,000 VND
Bot chờ xác nhận từ ngân hàng → tự động gửi link tài nguyên cho khách

Code ví dụ

from agentpay_vn import AgentPayClient
import asyncio
from datetime import datetime

class CourseBot:
    def __init__(self):
        self.client = AgentPayClient(base_url="http://localhost:8000")
        self.courses = {
            "python_advanced": {"price": 150000, "name": "Python Advanced"},
            "fastapi_pro": {"price": 200000, "name": "FastAPI Pro"},
        }

    async def buy_course(self, customer_id: str, course_key: str):
        """Xử lý yêu cầu mua khoá học"""
        if course_key not in self.courses:
            return {"error": "Khoá học không tồn tại"}

        course = self.courses[course_key]

        # Bước 1: Tạo yêu cầu thanh toán
        payment = await self.client.create_payment_request(
            amount=course["price"],
            description=f"Mua khoá {course['name']}",
            order_id=f"order_{customer_id}_{datetime.now().timestamp()}",
            merchant_account="1234567890",  # STK của bạn
        )

        # Bước 2: Gửi checkout URL cho khách
        checkout_message = f"""
        📚 {course['name']}
        Giá: {course['price']:,} VND

        Quét QR code này để thanh toán:
        {payment.checkout_url}
        """

        # Bước 3: Chờ settlement (cải tiến: chạy async không chặn)
        asyncio.create_task(
            self._wait_and_deliver(customer_id, course_key, payment.payment_id)
        )

        return {"message": checkout_message, "payment_id": payment.payment_id}

    async def _wait_and_deliver(self, customer_id: str, course_key: str, payment_id: str):
        """Chờ tiền về, rồi gửi khoá học"""
        # Chờ xác nhận thanh toán từ ngân hàng
        settlement = await self.client.await_settlement(
            payment_id=payment_id,
            timeout_seconds=3600  # Chờ tối đa 1 giờ
        )

        if settlement.status == "confirmed":
            # Tiền đã về!
            course_link = self.get_course_link(course_key)
            self.send_to_customer(
                customer_id,
                f"✅ Thanh toán thành công! Link khoá học: {course_link}"
            )
        else:
            self.send_to_customer(
                customer_id,
                "❌ Thanh toán không được xác nhận. Vui lòng thử lại."
            )

    def get_course_link(self, course_key: str) -> str:
        # Giả lập, trong thực tế sẽ lấy từ database
        return f"https://courses.example.com/{course_key}"

    def send_to_customer(self, customer_id: str, message: str):
        # Giả lập, thực tế dùng Telegram API, Discord API, v.v.
        print(f"[{customer_id}] {message}")

# Sử dụng
async def main():
    bot = CourseBot()
    result = await bot.buy_course("customer_789", "python_advanced")
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

Cấu hình MCP cho Claude Desktop

Nếu bạn muốn dùng AgentPay VN trực tiếp với Claude (qua Claude Desktop hoặc API), thêm cấu hình này vào file claude_desktop_config.json:

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "AGENTPAY_BASE_URL": "http://localhost:8000",
        "MERCHANT_ACCOUNT": "1234567890"
      }
    }
  }
}

Sau đó, bạn có thể nói với Claude:

"Tạo một yêu cầu thanh toán 500,000 VND cho đơn hàng #12345"

Claude sẽ tự gọi create_payment_request() và trả về checkout URL.

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

Nên làm	Không nên làm
✅ Dùng `await_settlement()` với timeout phù hợp	❌ Polling database mỗi giây (tốn resource)
✅ Lưu `payment_id` vào database để track	❌ Dựa vào client request để xác nhận tiền
✅ Bắt lỗi timeout và gửi thông báo lại	❌ Để customer chờ vô thời hạn
✅ Dùng `create_payment_request()` mỗi lần có đơn hàng	❌ Tạo một QR duy nhất cho tất cả khách
✅ Test với số tiền nhỏ trước (10,000 VND)	❌ Deploy trực tiếp với số tiền lớn
✅ Host MCP server riêng để an toàn	❌ Dùng public instance với data nhạy cảm

Ví dụ nâng cao: Quán cà phê tự động

Giả sử bạn có quán cà phê và muốn bot tự nhận đơn hàng + thanh toán:

# Bot tạo đơn, tính tiền, tạo QR
async def handle_coffee_order(items: list, customer_phone: str):
    total = sum(item["price"] for item in items)

    payment = await client.create_payment_request(
        amount=total,
        description=f"Đơn cà phê: {', '.join(i['name'] for i in items)}",
        order_id=f"cafe_{datetime.now().isoformat()}",
        merchant_account="1234567890",
    )

    # Gửi QR qua SMS/Zalo
    send_sms(customer_phone, f"Quét QR: {payment.checkout_url}")

    # Chờ thanh toán
    settlement = await client.await_settlement(payment.payment_id, timeout_seconds=600)

    if settlement.status == "confirmed":
        # Gửi tín hiệu tới quán để chuẩn bị đồ uống
        print(f"✅ Thanh toán OK, chuẩn bị: {items}")
        return {"status": "ready", "items": items}

Cơ sở này giảm được nhân viên thanh toán, tránh lỗi tính tiền, tăng throughput.

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

1. Tiền sẽ đi đâu? Có an toàn không?

Trả lời: AgentPay VN không giữ tiền. Mỗi khi khách chuyển khoản VietQR, tiền chuyển trực tiếp vào tài khoản ngân hàng của bạn (STK được cấu hình trong merchant_account). Chương trình chỉ xác nhận khi tiền về, không cần tín dụng hay ký quỹ.

2. Phải host MCP server riêng không?

Trả lời: Không bắt buộc. Bạn có thể: - Dùng SDK AgentPayClient trong code Python của mình (không cần server riêng) - Host MCP server riêng nếu muốn dùng với Claude hoặc agent framework khác

Hơn nữa, code là open-source, bạn tự host ở nhà/server của mình để an toàn tối đa.

3. Hỗ trợ thanh toán quốc tế không?

Trả lời: Hiện tại AgentPay VN tập trung vào VietQR trong nước. Nếu cần quốc tế, kết hợp với Stripe/PayPal trong cùng một flow là cách tốt nhất.

4. Nếu khách quét QR nhưng nhập sai số tiền?

Trả lời: AgentPay VN chỉ xác nhận nếu: - Số tiền khớp đúng - Được chuyển vào đúng STK merchant - Trong khoảng timeout

Nếu khách nhập sai số tiền, await_settlement() sẽ timeout và bạn có thể tạo payment request mới hoặc yêu cầu khách chuyển lại.

Hạn chế và cân nhắc

Phụ thuộc vào VietQR: Cần các bank hỗ trợ VietQR (SHB, Vietcombank, MB, ACB, v.v.)
Bank confirmation delay: Có thể mất 1-5 phút để ngân hàng xác nhận (tuỳ bank)
Test ở môi trường sandbox trước: Khuyến cáo dùng số tiền nhỏ để test trước khi deploy production

Tóm tắt nhanh

📦 Cài đặt: pip install agentpay-vn
🔑 3 dòng chính: create_payment_request() → gửi checkout_url → await_settlement()
🏦 Tiền vào đâu: Trực tiếp tài khoản ngân hàng của bạn (không giữ lại)
🤖 Cho AI Agent: Có MCP support, dùng với Claude hoặc agent framework
🔓 Open-source: MIT License, tự host được
⚡ Nhanh: Setup xong trong 10 phút
💰 Tiết kiệm: Không phí cố định, chỉ phí chuyển khoản ngân hàng (0-3k VND)

Bắt đầu nào!

Không có lý do gì để chờ đợi. AgentPay VN sẵn sàng giúp AI agent của bạn kiếm tiền từ hôm nay.

Các bước tiếp theo

Cài đặt: pip install agentpay-vn
Đọc tài liệu: https://agentpay.servicesai.vn/v1/docs
Xem code: https://github.com/phuocdu/agentpay-vn
Tạo payment request đầu tiên (với số tiền nhỏ để test)
Tích hợp vào bot của bạn

Nếu gặp vấn đề, GitHub issues là nơi tốt để hỏi hoặc góp ý.

Chúc bạn thành công! 🚀

Bắt đầu →

← Tất cả bài