AI Agent Thu Tiền VietQR Tự Động Bằng Python SDK

2026-10-11 · AgentPay VN

aipythonvietqragentpaymcp

Nỗi Đau: Khi AI Agent Của Bạn Không Thể Kiếm Tiền

Hãy tưởng tượng bạn vừa xây dựng một bot AI bán khóa học trực tuyến, hoặc một agent tư vấn tài chính tự động kiếm hoa hồng. Khách hàng đã sẵn sàng thanh toán, nhưng rồi... bạn phải nhảy ra để xử lý thủ công qua các nền tảng thanh toán phức tạp, chuyển tiền, đối soát. AI agent của bạn chỉ biết "trò chuyện" chứ không thể "gom tiền" một cách độc lập.

Đây chính là bài toán mà AgentPay VN giải quyết: cho phép AI agent tự động khởi tạo yêu cầu thanh toán VietQR, gửi mã QR cho khách hàng, và chờ xác nhận thanh toán từ ngân hàng — tất cả mà KHÔNG cần bạn can thiệp, và KHÔNG cần app nắm giữ tiền.

AgentPay VN Là Gì? Cách Nó Hoạt Động

AgentPay VN là một bộ công cụ open-source (giấy phép MIT) dành cho Python, gồm:

Python SDK (pip install agentpay-vn) – Thư viện để tạo yêu cầu thanh toán VietQR
MCP Server (agentpay-mcp) – Server cho phép AI (Claude, v.v.) gọi các hàm thanh toán như một "skill" tự nhiên
Bank Feed Integration – Tự động kiểm tra xác nhận thanh toán qua API ngân hàng

Điểm Khác Biệt Chính

Không giữ tiền: Mã QR VietQR trỏ trực tiếp đến tài khoản ngân hàng của bạn
Xác nhận lập tức: Bank feed tự động báo khi khách hàng thanh toán
Tích hợp AI: MCP server cho phép agent Claude, v.v. tự gọi hàm thanh toán
Hợp pháp & an toàn: Không xử lý dữ liệu tài khoản, chỉ là cầu nối

Qui Trình 3 Bước: Từ Yêu Cầu Đến Thanh Toán

AgentPay VN được thiết kế theo quy trình tối giản:

┌─────────────────────────────────────────────┐
│ 1. create_payment_request()                 │
│    → Tạo yêu cầu thanh toán                │
├─────────────────────────────────────────────┤
│ 2. send_checkout_url()                      │
│    → Gửi mã QR/URL checkout cho khách      │
├─────────────────────────────────────────────┤
│ 3. await_settlement()                       │
│    → Chờ xác nhận từ ngân hàng              │
└─────────────────────────────────────────────┘

Hướng Dẫn Cài Đặt & Cấu Hình

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

pip install agentpay-vn

Varification: Sau khi cài đặt, bạn có thể kiểm tra phiên bản:

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

Bước 2: Cấu Hình Thông Tin Ngân Hàng

Tạo file .env hoặc biến môi trường:

BANK_ACCOUNT_NUMBER=0123456789
BANK_ACCOUNT_NAME=Cty TNHH ABC
BANK_CODE=970012  # VietcomBank
VIETQR_API_KEY=your-vietqr-api-key

Bước 3: Khởi Tạo Client Python

from agentpay import AgentPayClient
import os

# Khởi tạo client với thông tin từ biến môi trường
client = AgentPayClient(
    bank_account=os.getenv("BANK_ACCOUNT_NUMBER"),
    bank_name=os.getenv("BANK_ACCOUNT_NAME"),
    bank_code=os.getenv("BANK_CODE"),
    api_key=os.getenv("VIETQR_API_KEY")
)

print("✅ AgentPay client đã sẵn sàng!")

Ví Dụ Thực Tế #1: Bot Bán Khóa Học Online

Hãy tưởng tượng bạn có một bot tư vấn học lập trình. Khi khách hàng quyết định mua khóa học, agent sẽ:

from agentpay import AgentPayClient, PaymentRequest
import asyncio
from datetime import datetime, timedelta

# Khởi tạo
client = AgentPayClient(
    bank_account="0123456789",
    bank_name="Học Lập Trình VN",
    bank_code="970012"
)

async def sell_course(customer_name, customer_email, course_id, price_vnd):
    """
    Bot tự động bán khóa học qua VietQR

    Args:
        customer_name: Tên khách hàng
        customer_email: Email khách hàng
        course_id: Mã khóa học (vd: 'python-101')
        price_vnd: Giá tiền (VND)
    """

    # Bước 1: Tạo yêu cầu thanh toán
    payment_req = PaymentRequest(
        transaction_id=f"COURSE_{course_id}_{int(datetime.now().timestamp())}",
        amount=price_vnd,
        description=f"Khóa {course_id} - {customer_name}",
        customer_email=customer_email,
        expires_at=datetime.now() + timedelta(hours=24)  # Hết hạn sau 24h
    )

    # Bước 2: Tạo mã QR
    payment = await client.create_payment_request(payment_req)
    print(f"📱 QR Code URL: {payment.checkout_url}")
    print(f"💰 Số tiền: {payment_req.amount:,} VND")

    # Bước 3: Chờ xác nhận thanh toán
    settlement = await client.await_settlement(
        transaction_id=payment_req.transaction_id,
        timeout_seconds=3600  # Chờ tối đa 1 giờ
    )

    if settlement.status == "confirmed":
        print(f"✅ Thanh toán thành công! Số tiền: {settlement.amount:,} VND")
        print(f"🎓 Khóa học {course_id} đã được kích hoạt cho {customer_email}")
        # Tự động gửi link khóa học, cấp quyền truy cập, v.v.
        return True
    else:
        print(f"❌ Thanh toán thất bại hoặc hết hạn")
        return False

# Sử dụng
asyncio.run(sell_course(
    customer_name="Nguyễn Văn A",
    customer_email="a@example.com",
    course_id="python-101",
    price_vnd=299000
))

Giải thích từng bước: - PaymentRequest: Định nghĩa yêu cầu thanh toán với transaction_id duy nhất, số tiền, mô tả, và thời gian hết hạn - create_payment_request(): Tạo mã QR VietQR, trả về checkout_url để gửi cho khách - await_settlement(): Chờ xác nhận từ ngân hàng (non-blocking), tự động kiểm tra trạng thái - Khi settlement.status == "confirmed", bot tự động gửi link khóa học hoặc cấp quyền truy cập

Tích Hợp MCP Để AI Agent Tự Gọi Hàm

Nếu bạn sử dụng Claude (hoặc AI khác hỗ trợ MCP), bạn có thể cấu hình AgentPay MCP server để agent gọi hàm thanh toán một cách tự nhiên:

Cấu Hình MCP Server (JSON cho Claude)

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "BANK_ACCOUNT_NUMBER": "0123456789",
        "BANK_ACCOUNT_NAME": "Công Ty ABC",
        "BANK_CODE": "970012",
        "VIETQR_API_KEY": "your-api-key"
      }
    }
  }
}

Sau khi cấu hình, Claude sẽ có thể gọi các hàm như:

User: "Tạo yêu cầu thanh toán 500k cho khách Nguyễn Văn B"

Claude:
→ Gọi agentpay.create_payment_request(
     transaction_id="txn_12345",
     amount=500000,
     description="Thanh toán cho Nguyễn Văn B"
  )
→ Nhận lại QR code URL
→ Gửi mã QR cho khách hàng
→ Tự động chờ xác nhận
→ Báo cáo kết quả

Agent không cần prompt hoặc lệnh riêng — nó tự biết cách sử dụng hàm!

Ví Dụ Thực Tế #2: Quán Cà Phê – Bán Hàng Qua Chatbot

Một quán cà phê muốn có chatbot bán cà phê giao hàng:

from agentpay import AgentPayClient, PaymentRequest
import asyncio

client = AgentPayClient(
    bank_account="9876543210",
    bank_name="Cà Phê Hạnh Phúc",
    bank_code="970445"  # Techcombank
)

class CoffeeBot:
    def __init__(self):
        self.menu = {
            "cappuccino": {"price": 45000, "name": "Cà Phê Cappuccino"},
            "latte": {"price": 50000, "name": "Cà Phê Latte"},
            "espresso": {"price": 35000, "name": "Espresso đôi"}
        }

    async def process_order(self, items_dict, customer_phone):
        """
        Xử lý đơn hàng và tạo thanh toán
        items_dict: {"cappuccino": 2, "latte": 1}
        """
        total = sum(
            self.menu[item]["price"] * qty
            for item, qty in items_dict.items()
        )

        # Tạo yêu cầu thanh toán
        order_desc = ", ".join([
            f"{qty}x {self.menu[item]['name']}"
            for item, qty in items_dict.items()
        ])

        payment_req = PaymentRequest(
            transaction_id=f"COFFEE_{customer_phone}_{int(datetime.now().timestamp())}",
            amount=total,
            description=f"Đơn cà phê: {order_desc}"
        )

        payment = await client.create_payment_request(payment_req)
        print(f"🛍️ Tổng cộng: {total:,} VND")
        print(f"📱 Quét mã QR: {payment.checkout_url}")

        # Chờ thanh toán
        settlement = await client.await_settlement(
            transaction_id=payment_req.transaction_id,
            timeout_seconds=600  # 10 phút
        )

        if settlement.status == "confirmed":
            print(f"✅ Đơn hàng xác nhận! Sẽ giao hàng trong 30 phút.")
            # Gửi SMS/email xác nhận cho khách
            return True
        else:
            print(f"⏰ Hết thời gian chờ thanh toán")
            return False

# Sử dụng
bot = CoffeeBot()
asyncio.run(bot.process_order(
    items_dict={"cappuccino": 2, "latte": 1},
    customer_phone="0912345678"
))

Nên Làm & Không Nên Làm Khi Dùng AgentPay VN

✅ NÊN LÀM	❌ KHÔNG NÊN LÀM
Lưu `transaction_id` duy nhất cho mỗi đơn hàng	Dùng lại `transaction_id` cũ
Thiết lập `expires_at` phù hợp (VD: 24h cho khóa học)	Để mã QR hết hạn mà không thông báo khách
Xử lý exception khi `await_settlement()` timeout	Chỉ chờ mà không có fallback
Lưu `settlement.amount` và `settlement.timestamp` để audit	Tin tưởng mà không kiểm tra
Sử dụng MCP server để AI tự gọi hàm	Hardcode toàn bộ logic thanh toán vào prompt
Cấu hình bank_code chính xác	Nhầm bank_code dẫn đến QR sai
Test với số tiền nhỏ trước	Bắt đầu bằng số tiền lớn

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

1. Tiền sẽ về tài khoản nào?

Tiền về tài khoản ngân hàng bạn cấu hình trong BANK_ACCOUNT_NUMBER. AgentPay VN chỉ là cầu nối để tạo mã QR, không nắm giữ tiền.

2. Mất bao lâu để xác nhận thanh toán?

Thường từ 1–5 phút tùy ngân hàng. await_settlement() sẽ chờ tối đa thời gian bạn cấu hình (VD: 3600 giây = 1 giờ). Bạn có thể tùy chỉnh timeout_seconds.

3. Có phí nào thêm không?

AgentPay VN là open-source (miễn phí). Phí chuyển khoản VietQR do ngân hàng tính (thường 0–2,000 VND tùy ngân hàng). Không có phí từ AgentPay.

4. Tôi có thể sử dụng nó cho bot trên Telegram, Discord không?

Có! Bạn chỉ cần gọi client.create_payment_request() để lấy checkout_url, rồi gửi link QR cho khách qua Telegram/Discord bot của bạn. Khi khách quét QR, hàng sẽ được xác nhận tự động.

Tóm Tắt Nhanh

🚀 AgentPay VN: Python SDK + MCP server để AI agent tự thu tiền VietQR
🏦 Tiền trực tiếp vào ngân hàng: Không nắm giữ, không rủi ro
📱 Quy trình 3 bước: create_payment_request → send checkout_url → await_settlement
🤖 Tích hợp MCP: Claude/AI tự gọi hàm thanh toán mà không cần prompt riêng
💻 Easy Install: pip install agentpay-vn
📚 Docs & GitHub: https://agentpay.servicesai.vn/v1/docs & https://github.com/phuocdu/agentpay-vn
✅ Hợp pháp & An toàn: MIT license, không xử lý dữ liệu tài khoản

Bước Tiếp Theo: Bắt Đầu Ngay Hôm Nay

Cài đặt SDK: bash pip install agentpay-vn
Lấy thông tin ngân hàng: - Số tài khoản - Tên chủ tài khoản - Mã ngân hàng (bank_code) - API Key từ VietQR
Chạy ví dụ đầu tiên: Copy ví dụ "Bot Bán Khóa Học" hoặc "Quán Cà Phê" ở trên, điều chỉnh thông tin ngân hàng, rồi chạy!
Đọc docs đầy đủ: - 📖 AgentPay VN Documentation - 🔧 GitHub Repository
Tích hợp MCP (tuỳ chọn): Nếu bạn dùng Claude hoặc AI khác, cấu hình MCP server để agent tự gọi hàm thanh toán.

Đừng để AI agent của bạn chỉ biết "nói chuyện" — hãy cho nó khả năng "kiếm tiền" ngay hôm nay! 🚀

Bắt đầu →

← Tất cả bài