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

2026-10-04 · AgentPay VN

aipythonvietqrmcpthanh-toán

Tình huống: Bot bạn cần tiền thật, không phải lời nói suông

Bạn vừa xây dựng một AI agent thông minh: nó có thể giải bài tập cho học sinh, tư vấn kinh doanh, hoặc quản lý shop online. Khách hàng yêu thích, lượt truy cập tăng — nhưng bạn vẫn chưa kiếm được đồng nào.

Tại sao? Vì kết nối thanh toán với AI agent vẫn còn phức tạp. Bạn phải: - Tích hợp gateway trung gian (Stripe, Paypal) phí cắt cổ - Đợi 5-7 ngày rút tiền - Quản lý hàng loạt API, webhook, trạng thái thanh toán - Lo lắng tiền khách có bị "treo" ở hệ thống của bạn không

AgentPay VN ra đời để giải quyết đúng vấn đề này: cho phép AI agent tự động thu tiền VietQR, trực tiếp vào tài khoản ngân hàng của bạn, mà KHÔNG cần giữ tiền lâu.

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

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

Tạo yêu cầu thanh toán từ AI agent của bạn
Sinh mã QR VietQR (không phí bên thứ ba)
Theo dõi settlement qua bank feed tự động
Agent xử lý logic tiếp theo khi thanh toán xác nhận

Điểm mạnh: - Không giữ tiền: QR code trỏ thẳng vào tài khoản ngân hàng của bạn - Thanh toán tức thì: Khoá học được mở, hàng được giao ngay khi tiền về - Đơn giản: 3 dòng code chính, tích hợp vào agent trong vài phút - Mã nguồn mở: Bạn hoàn toàn kiểm soát, không lo bị khóa/thay đổi điều khoản

Cài đặt AgentPay VN

Bước 1: Cài Python SDK

Mở terminal và chạy:

pip install agentpay-vn

Vậy thôi. Dependency chính là httpx (gọi API bank feed) và qrcode (sinh QR).

Bước 2: Cài MCP Server (nếu dùng Claude)

Nếu bạn muốn cho Claude (hoặc AI agent khác) tự gọi các function của AgentPay, cài MCP server:

pip install agentpay-mcp

Rồi thêm vào file cấu hình Claude (.cursor/codebase-chat.json hoặc tương tự):

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "AGENTPAY_MERCHANT_ID": "your_merchant_id",
        "AGENTPAY_BANK_ACCOUNT": "1234567890",
        "AGENTPAY_BANK_CODE": "VIETCOMBANK"
      }
    }
  }
}

(Bạn sẽ nhận MERCHANT_ID từ trang docs hoặc liên hệ AgentPay)

Luồng 3 bước: Từ yêu cầu đến settlement

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

from agentpay_vn import AgentPay

# Khởi tạo client
pay = AgentPay(
    merchant_id="your_merchant_id",
    api_key="your_api_key"
)

# Tạo yêu cầu thanh toán
payment = pay.create_payment_request(
    amount=99000,  # VND
    description="Khoá học Python nâng cao - Phần 1",
    customer_name="Nguyễn Văn A",
    customer_phone="0901234567",
    order_id="ORDER_001",  # ID duy nhất của bạn
    metadata={"course_id": "python_101", "lesson": "1"}
)

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

Giải thích: - create_payment_request() gửi yêu cầu đến server AgentPay - Server tạo QR VietQR trỏ vào tài khoản ngân hàng + metadata bạn cung cấp - Hàm trả về object chứa qr_code_url (ảnh QR), checkout_url (trang thanh toán online), và id (để track sau)

Bước 2: Gửi QR cho khách hàng

# Trong bot Telegram, Discord, web, v.v.
checkout_message = f"""
📱 Quét mã QR để thanh toán:
{payment.qr_code_url}

Hoặc click: {payment.checkout_url}

Số tiền: {99000:,} VND
Mô tả: {payment.description}
"""

# Gửi message cho khách (tuỳ từng nền tảng)
await telegram_bot.send_message(chat_id, checkout_message)

Bước 3: Chờ settlement & xử lý logic

import asyncio
from agentpay_vn import SettlementStatus

async def wait_for_payment(payment_id, timeout=300):
    """
    Chờ thanh toán xác nhận qua bank feed (tối đa 5 phút)
    """
    pay = AgentPay(merchant_id="...", api_key="...")

    start_time = asyncio.get_event_loop().time()
    while asyncio.get_event_loop().time() - start_time < timeout:
        settlement = pay.await_settlement(payment_id)

        if settlement.status == SettlementStatus.CONFIRMED:
            print(f"✅ Thanh toán thành công! {settlement.amount} VND")
            # Mở khoá học, gửi file, kích hoạt account...
            await unlock_course(settlement.metadata["course_id"])
            return settlement

        elif settlement.status == SettlementStatus.FAILED:
            print(f"❌ Thanh toán thất bại: {settlement.error_message}")
            return None

        # Chưa xác nhận, chờ 2 giây rồi kiểm tra lại
        await asyncio.sleep(2)

    print("⏱️ Hết thời gian chờ")
    return None

# Sử dụng
await wait_for_payment(payment.id)

Cách hoạt động: - await_settlement() truy vấn bank feed từ ngân hàng (qua API an toàn) - Nó trả về trạng thái: PENDING (chưa có tiền), CONFIRMED (tiền đã vào), hoặc FAILED - Khi xác nhận, agent tự động kích hoạt hành động kế tiếp

Ví dụ thực tế: Bot bán khoá học online

Hãy tưởng tượng bạn làm một chatbot dạy lập trình:

import asyncio
from agentpay_vn import AgentPay

class CourseBot:
    def __init__(self):
        self.pay = AgentPay(merchant_id="...", api_key="...")
        self.courses = {
            "python_101": {"name": "Python cơ bản", "price": 99000},
            "python_advanced": {"name": "Python nâng cao", "price": 199000}
        }

    async def sell_course(self, user_id, course_id):
        """
        Khách yêu cầu mua khoá học → bot tạo QR → chờ thanh toán → mở khoá
        """
        course = self.courses[course_id]

        # 1️⃣ Tạo yêu cầu thanh toán
        payment = self.pay.create_payment_request(
            amount=course["price"],
            description=f"Khoá học: {course['name']}",
            customer_name=f"User {user_id}",
            order_id=f"USER_{user_id}_{course_id}",
            metadata={"course_id": course_id, "user_id": user_id}
        )

        # 2️⃣ Gửi QR cho khách
        print(f"📱 Quét QR để thanh toán {course['price']:,} VND:")
        print(payment.qr_code_url)

        # 3️⃣ Chờ xác nhận
        settlement = self.pay.await_settlement(payment.id)

        if settlement.status == "CONFIRMED":
            # Mở khoá học
            await self.unlock_course_for_user(
                user_id,
                course_id,
                settlement.amount
            )
            print(f"✅ {settlement.amount:,} VND đã nhận. Khoá học '{course['name']}' đã mở!")
            return True
        else:
            print("❌ Thanh toán không thành công")
            return False

    async def unlock_course_for_user(self, user_id, course_id, paid_amount):
        # Logic lưu vào database / tạo tài khoản / gửi link
        print(f"🔓 Mở khoá {course_id} cho user {user_id}")

# Sử dụng
bot = CourseBot()
await bot.sell_course(user_id=12345, course_id="python_101")

Kịch bản: 1. Khách: "Tôi muốn mua khoá Python cơ bản" 2. Bot tạo QR, gửi ảnh 3. Khách quét → chuyển 99.000 VND 4. Tiền vào tài khoản ngân hàng của bạn trong vòng 30 giây 5. Bot phát hiện → mở khoá course ngay 6. Khách: "Wow, nó instant! 🚀"

So sánh: AgentPay VN vs giải pháp khác

Tiêu chí	AgentPay VN	Stripe	PayPal	Momo API
Thời gian rút tiền	Tức thì (QR)	2-5 ngày	3-7 ngày	1 ngày
Phí giao dịch	0% (ngân hàng)	2.9% + 4.9k	3.49% + 5k	0.5-2%
Giữ tiền	Không	Có (escrow)	Có	Có
Setup phức tạp	5 phút	1 giờ	1 giờ	30 phút
Mã nguồn mở	✅ MIT	❌	❌	❌
Hỗ trợ MCP/AI	✅ Native	❌ Phải wrapper	❌	❌
VietQR (Việt Nam)	✅	❌	❌	✅

Nên dùng AgentPay VN khi: - Bạn ở Việt Nam, khách hàng dùng VietQR - Cần thanh toán tức thì (không thể chờ 5 ngày) - Muốn giảm phí, không lo bị lock-in - Xây dựng AI agent cần tự động quản lý tiền

Không nên dùng AgentPay VN khi: - Bạn cần hỗ trợ quốc tế (chỉ có VietQR) - Cần refund/chargeback phức tạp (tính năng tối thiểu)

Cấu hình nâng cao: Custom metadata & webhook

Lưu thêm thông tin khách hàng

payment = pay.create_payment_request(
    amount=250000,
    description="Dịch vụ thiết kế logo",
    customer_name="Công ty ABC",
    customer_email="contact@abc.com",
    customer_phone="0912345678",
    order_id="DESIGN_001",
    metadata={
        "service_type": "logo_design",
        "quantity": 3,
        "deadline": "2025-02-15",
        "client_company": "ABC Corp",
        "designer_assigned": "john_doe"
    }
)

Metadata sẽ được trả lại khi bạn query await_settlement(), giúp agent biết phải làm gì tiếp theo.

Tích hợp webhook (tuỳ chọn)

AgentPay có thể POST tới endpoint của bạn khi thanh toán xác nhận:

payment = pay.create_payment_request(
    amount=99000,
    description="...",
    webhook_url="https://yoursite.com/agentpay/webhook"
)

# Trong Flask/FastAPI app của bạn:
from flask import Flask, request

app = Flask(__name__)

@app.route("/agentpay/webhook", methods=["POST"])
def handle_settlement():
    data = request.json

    # data = {
    #   "payment_id": "...",
    #   "status": "CONFIRMED",
    #   "amount": 99000,
    #   "metadata": {...}
    # }

    # Xử lý: mở khoá, tạo hóa đơn, v.v.
    unlock_course(data["metadata"]["course_id"])

    return {"status": "ok"}, 200

Nên & không nên

✅ Nên làm

Lưu payment.id để track sau: ORDER_001 → PAYMENT_UUID_XYZ
Set timeout hợp lý (300s = 5 phút cho VietQR)
Log tất cả giao dịch: payment_id, amount, status, timestamp
Test trước bằng test mode (nếu AgentPay cung cấp)
Xử lý retry: nếu await_settlement fail, chờ 5 giây rồi thử lại (tối đa 3 lần)

❌ Không nên làm

Giả sử thanh toán thành công mà không gọi await_settlement() (!)
Để client chờ quá 10 phút vì QR VietQR thường confirm trong 30-60 giây
Hardcode merchant_id/api_key vào code: dùng env variable
Gửi tiền cho khách trước khi check SettlementStatus.CONFIRMED
Quên giữ backup của payment records (AgentPay không phải ngân hàng)

Hỏi đáp thường gặp

Q1: Nếu khách quét QR nhưng không gửi tiền, bot sẽ chờ mãi không?

Không. await_settlement() có timeout mặc định 5 phút. Sau đó trả về PENDING, và bạn có thể bắt exception, gửi reminder, hoặc hủy yêu cầu.

Q2: Tiền về tài khoản mất bao lâu?

VietQR qua hệ thống interbank của Việt Nam: 30 giây - 2 phút. AgentPay sẽ phát hiện qua bank feed trong vòng 5 giây kể từ đó.

Q3: Nếu khách tình cờ gửi sai số tiền hoặc sai tài khoản?

Sai số tiền: await_settlement() sẽ không xác nhận (agent chỉ nhận nếu match chính xác amount)
Sai tài khoản: không ảnh hưởng AgentPay, vì khách quét QR trỏ vào tài khoản bạn cung cấp

Nếu cần refund, bạn gọi thủ công từ app ngân hàng (AgentPay không giữ tiền).

Q4: Có hỗ trợ thanh toán lặp (subscription) không?

Hiện tại AgentPay là one-time payment. Để subscription, bạn cần gọi create_payment_request() định kỳ hàng tháng hoặc dùng tool khác.

Tóm tắt nhanh

📦 Cài đặt: pip install agentpay-vn
🏗️ 3 bước: create_payment_request() → gửi QR → await_settlement()
💰 Lợi ích: Không phí (so với Stripe), thanh toán tức thì, mã nguồn mở
🤖 AI-friendly: MCP server cho Claude/Agent tự gọi hàm
🇻🇳 VietQR native: Không cần gateway quốc tế
⚡ Nhanh: Tiền vào tài khoản trong 30 giây
🔒 An toàn: Bạn hoàn toàn kiểm soát, QR trỏ vào tài khoản của chính bạn

Bước tiếp theo

Hôm nay, bạn có thể:

Cài SDK: pip install agentpay-vn
Copy ví dụ CourseBot ở trên
Lấy merchant_id từ https://agentpay.servicesai.vn/v1/docs
Test tạo payment request → quét QR → chờ settlement

Kiểm tra kho GitHub:
https://github.com/phuocdu/agentpay-vn — có thêm ví dụ Telegram bot, FastAPI integration, v.v.

Tài liệu đầy đủ:
https://agentpay.servicesai.vn/v1/docs — API reference, error codes, test account

Chúc bạn xây dựng agent kiếm tiền thành công! 🚀 Nếu có câu hỏi, hãy mở issue trên GitHub hoặc inbox tác giả. AgentPay VN vẫn đang phát triển, feedback của bạn rất quý giá.

Bắt đầu →

← Tất cả bài