AI Agent thu tiền VietQR tự động bằng Python SDK

2026-07-01 · AgentPay VN

aipythonvietqrpaymentmcp

Tình Huống: Khi Thanh Toán Trở Thành Nút Cổ Chai

Bạn vừa xây dựng một chatbot AI thông minh cho cửa hàng trực tuyến của mình. Bot biết cách tư vấn sản phẩm, trả lời câu hỏi khách hàng, thậm chí còn có thể tạo hóa đơn. Nhưng khi đến bước thanh toán, bạn phải bắt khách hàng rời khỏi cuộc trò chuyện, vào một trang web riêng, quét QR thủ công.

Lúc đó, bạn nghĩ: "Tại sao AI agent không thể tạo QR, gửi link và tự động xác nhận thanh toán luôn nhỉ?"

Bài viết này sẽ cho bạn thấy cách làm điều đó với AgentPay VN — một SDK Python nhẹ nhàng, mã nguồn mở, được thiết kế riêng cho các AI agent cần thu tiền qua VietQR.

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

AgentPay VN là một Python SDK mã nguồn mở (MIT License) kết hợp với MCP server, cho phép AI agent:

Điểm quan trọng nhất: AgentPay VN KHÔNG bao giờ giữ tiền của bạn. Tiền chuyển trực tiếp vào tài khoản ngân hàng của bạn. SDK chỉ đóng vai trò "trung gian tạo QR và kiểm tra trạng thái".

So với các giải pháp payment gateway khác, AgentPay VN được xây dựng từ đầu để tích hợp với AI agent và LLM — không cần phức tạp callback, webhook hay session management.

Các Nỗi Đau Khi Tích Hợp Thanh Toán Với AI Agent

Vấn đề Giải pháp truyền thống AgentPay VN
Không thể tạo QR lập trình Cần API phức tạp, xác thực 3 dòng code Python
Khó kiểm tra trạng thái thanh toán Poll webhook, logic phức await_settlement() chặn đơn giản
Tiền bị "treo" ở payment gateway Phí cao, rút tiền mất thời gian Trực tiếp vào tài khoản ngân hàng
Tích hợp MCP khó khăn Viết tool custom rồi debug MCP server có sẵn, chuẩn bị dùng
Bảo mật token API Giấu key, quản lý secret Không cần token, dùng VietQR chuẩn

Cài Đặt AgentPay VN — Chỉ Một Lệnh

Trước tiên, đảm bảo bạn có Python 3.8+:

pip install agentpay-vn

Đó là tất cả. Không cần config file, không cần environment variable bí mật.

Nếu bạn muốn dùng với Claude hoặc các AI agent khác qua MCP, cài thêm:

pip install agentpay-mcp

3 Bước Cốt Lõi: Quy Trình Thanh Toán Của AI Agent

AgentPay VN tuân theo một quy trình siêu đơn giản:

  1. create_payment_request() — AI agent yêu cầu tạo QR
  2. send checkout_url() — Gửi link cho khách hàng
  3. await_settlement() — Chờ tiền về tài khoản

Hãy xem code thực tế:

from agentpay_vn import AgentPayClient
import asyncio

# Khởi tạo client (không cần API key)
client = AgentPayClient()

async def bot_charge_customer():
    # Bước 1: Tạo yêu cầu thanh toán
    # amount: số tiền (VND)
    # description: mô tả, VD "Khoá học Python Advanced"
    # merchant_id: ID của bạn (lấy từ VietQR)
    payment_req = await client.create_payment_request(
        amount=299000,
        description="Khoá học Python nâng cao - AgentPay VN",
        merchant_id="your_merchant_id"
    )

    # payment_req.checkout_url: link QR code
    # payment_req.transaction_id: ID để theo dõi
    print(f"📱 Quét QR tại: {payment_req.checkout_url}")

    # Bước 2: Gửi link cho khách hàng
    # (Trong thực tế, chatbot sẽ gửi link này)
    customer_message = f"Bạn cần thanh toán 299.000 đ. Link QR: {payment_req.checkout_url}"

    # Bước 3: Chờ xác nhận thanh toán
    # await_settlement() sẽ block cho đến khi tiền vào hoặc timeout
    settlement = await client.await_settlement(
        transaction_id=payment_req.transaction_id,
        timeout_seconds=300  # 5 phút
    )

    if settlement.is_confirmed:
        print(f"✅ Thanh toán thành công! Số tiền: {settlement.amount} VND")
        print(f"🏦 Số tài khoản đích: {settlement.bank_account}")
        # Bây giờ agent có thể cấp quyền truy cập khoá học cho khách
    else:
        print(f"⏱️ Hết timeout, khách chưa thanh toán")

# Chạy
asyncio.run(bot_charge_customer())

Giải thích từng dòng:

Tích Hợp Với MCP Server Cho Claude Và LLM Khác

Nếu bạn muốn AI agent của Claude tự gọi AgentPay mà không cần code Python trực tiếp, hãy dùng MCP server:

1. Cài đặt MCP server:

pip install agentpay-mcp
agentpay-mcp --host 0.0.0.0 --port 3001

2. Cấu hình Claude (trong file cơ sở dữ liệu của bạn):

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "AGENTPAY_MERCHANT_ID": "your_merchant_id",
        "AGENTPAY_BANK_CODE": "970416"  // VietQR bank code
      }
    }
  }
}

3. Khi đó, Claude sẽ tự động có 3 tool:

Bạn không cần viết thêm code nào — Claude sẽ tự gọi chúng khi cần.

Kịch Bản Thực Tế: Bot Bán Khoá Học Online

Hãy tưởng tượng bạn có một chatbot bán khoá học lập trình:

from agentpay_vn import AgentPayClient
import asyncio

class CourseSellingBot:
    def __init__(self):
        self.client = AgentPayClient()
        self.courses = {
            "python_beginner": {
                "name": "Python Dành Cho Người Mới",
                "price": 199000,
                "access_link": "https://edu.example.com/python-beginner"
            },
            "python_advanced": {
                "name": "Python Nâng Cao - Django & FastAPI",
                "price": 499000,
                "access_link": "https://edu.example.com/python-advanced"
            }
        }

    async def sell_course(self, customer_name: str, course_id: str):
        """Quy trình bán khoá từ đầu đến cuối"""

        if course_id not in self.courses:
            return f"❌ Khoá {course_id} không tồn tại"

        course = self.courses[course_id]

        # Bước 1: Tạo yêu cầu thanh toán
        payment = await self.client.create_payment_request(
            amount=course["price"],
            description=f"Khoá học: {course['name']}",
            merchant_id="your_merchant_id"
        )

        response = f"""Xin chào {customer_name}! 🎓

Bạn chọn: {course['name']}
Giá: {course['price']:,} VND

🔗 Link QR thanh toán: {payment.checkout_url}

Hãy quét QR trong ứng dụng ngân hàng của bạn để thanh toán.
        """

        # Bước 2: Chờ thanh toán (chạy async background)
        asyncio.create_task(self._grant_access_after_payment(payment.transaction_id, customer_name, course))

        return response

    async def _grant_access_after_payment(self, transaction_id: str, customer_name: str, course: dict):
        """Cấp quyền truy cập sau khi thanh toán thành công"""
        settlement = await self.client.await_settlement(
            transaction_id=transaction_id,
            timeout_seconds=3600  # 1 giờ
        )

        if settlement.is_confirmed:
            # Gửi email hoặc lưu vào database
            print(f"✅ {customer_name} đã thanh toán thành công!")
            print(f"📧 Gửi link truy cập: {course['access_link']} cho {customer_name}")
            # grant_course_access(customer_name, course['access_link'])
        else:
            print(f"⏱️ {customer_name} chưa thanh toán trong 1 giờ")

# Sử dụng
async def main():
    bot = CourseSellingBot()
    message = await bot.sell_course("Nguyễn Văn A", "python_advanced")
    print(message)
    # Bot sẽ tự động chờ thanh toán ở background
    await asyncio.sleep(3600)  # Chừa 1 giờ cho khách thanh toán

asyncio.run(main())

Điều gì xảy ra:

  1. Khách hàng chat với bot, chọn khoá học
  2. Bot tạo QR và gửi link
  3. Bot chờ thanh toán ở background (không block lệnh khác)
  4. Khi tiền về tài khoản (qua VietQR), settlement.is_confirmed = True
  5. Bot tự động gửi email với link truy cập khoá học
  6. Khách vui vẻ, bạn nhận tiền, không mất phí

Những Điều Nên Biết Khi Triển Khai

✅ Nên làm:

❌ Không nên làm:

Nâng Cao: Retry Logic Và Error Handling

Trong sản xuất, bạn cần xử lý lỗi:

from agentpay_vn import AgentPayClient, PaymentException
import asyncio

async def safe_charge(amount: int, description: str, max_retries: int = 3):
    client = AgentPayClient()

    for attempt in range(max_retries):
        try:
            payment = await client.create_payment_request(
                amount=amount,
                description=description,
                merchant_id="your_merchant_id"
            )
            print(f"✅ Tạo QR thành công: {payment.checkout_url}")

            # Chờ thanh toán với timeout
            settlement = await asyncio.wait_for(
                client.await_settlement(payment.transaction_id),
                timeout=300
            )

            if settlement.is_confirmed:
                return {"status": "success", "settlement": settlement}
            else:
                return {"status": "timeout", "transaction_id": payment.transaction_id}

        except asyncio.TimeoutError:
            print(f"⏱️ Lần {attempt + 1}: Timeout, thử lại...")
        except PaymentException as e:
            print(f"❌ Lần {attempt + 1}: Lỗi API - {e}")
            if attempt == max_retries - 1:
                return {"status": "error", "message": str(e)}

        await asyncio.sleep(2 ** attempt)  # Backoff exponential

    return {"status": "failed", "reason": "Max retries exceeded"}

# Sử dụng
result = asyncio.run(safe_charge(100000, "Thanh toán đơn hàng"))
print(result)

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

Q: AgentPay VN có phí không?
A: Không! Đó là open-source (MIT). Bạn chỉ phải trả phí cho ngân hàng (thường 0-2% tùy VietQR partner).

Q: Tiền đó lưu ở AgentPay bao lâu?
A: 0 giây! Tiền chuyển trực tiếp vào tài khoản ngân hàng của bạn. AgentPay chỉ tạo QR, không giữ tiền.

Q: Nếu khách quét QR nhưng không gửi đủ tiền?
A: await_settlement() sẽ không confirm cho đến khi số tiền khớp hoặc hết timeout. Bạn có thể kiểm tra số tiền thực tế ở settlement.amount.

Q: Có thể dùng với FastAPI hoặc Flask không?
A: Có! AgentPayClient hỗ trợ async/await nên chạy tốt với FastAPI. FastAPI + AgentPay = app bán hàng sẵn sàng.

Tóm Tắt Nhanh

Kết Luận

AI agent có thể "kiếm tiền" thực sự. Với AgentPay VN, bạn không cần phức tạp hóa quy trình — chỉ 3 dòng code, agent đã tự động:

  1. Tạo QR từ yêu cầu của khách
  2. Gửi link
  3. Chờ xác nhận tiền vào tài khoản

Có thể bạn đang bán khoá học, giao dịch dịch vụ AI, hoặc bot tư vấn tài chính — AgentPay VN sẵn sàng xử lý thanh toán để bạn tập trung vào giá trị thực sự.

Bắt đầu ngay hôm nay:

Happy coding! 🎉

Bắt đầu →

← Tất cả bài