Hướng dẫn: AI Agent tự thu tiền VietQR bằng Python & AgentPay

2026-10-02 · AgentPay VN

aipythonvietqrmcpthanh toán

Tình huống: Bạn bán khoá học online, nhưng mỗi khi có học viên mới, bạn phải gửi QR code thủ công, chờ thông báo chuyển khoản, rồi cấp tài khoản. Mệt mỏi, chậm, dễ sai sót.

Nếu có một AI agent tự động xử lý toàn bộ quy trình — từ tạo hóa đơn, gửi QR, xác nhận thanh toán, cho đến kích hoạt khoá học — thì bạn sẽ tiết kiệm hàng giờ mỗi tuần và không bao giờ bỏ sót khách hàng nào.

Đó chính là sức mạnh của AgentPay VN — một giải pháp open-source cho phép AI agent thực hiện toàn quy trình thu tiền VietQR mà không bao giờ giữ tiền, chỉ trỏ thẳng đến tài khoản ngân hàng thật của bạn.

AgentPay VN là gì? Tại sao bạn nên dùng nó?

AgentPay VN là một Python SDK + MCP server cho phép các AI agent (như Claude, GPT, hay bot tự xây dựng) tự động: - Tạo yêu cầu thanh toán (payment request) - Sinh QR code VietQR - Gửi checkout URL cho khách hàng - Chờ xác nhận settlement từ ngân hàng - Kích hoạt hành động tiếp theo (cấp tài khoản, gửi email, lưu database)

Điểm khác biệt quan trọng: AgentPay không giữ một đồng nào. Khi khách hàng scan QR, tiền chuyển thẳng vào tài khoản ngân hàng của bạn. AgentPay chỉ đóng vai trò "người bạn thông minh" giúp AI agent giao tiếp với API ngân hàng.

Cơ chế hoạt động: 3 bước đơn giản

Quy trình để một AI agent thu tiền qua VietQR:

1. create_payment_request() 
   → Tạo yêu cầu thanh toán + sinh QR

2. send_checkout_url() 
   → Gửi URL/QR đến khách

3. await_settlement() 
   → Chờ ngân hàng xác nhận tiền về

Không có server trung gian, không có holding balance, không có phí ẩn. Đơn giản, minh bạch, an toàn.

Cài đặt & Thiết lập ban đầu

1. Cài đặt Python SDK

pip install agentpay-vn

Thế là xong. Không cần tạo tài khoản trung gian, không cần đăng ký dịch vụ khác.

2. Cấu hình cho MCP Server (nếu dùng Claude/AI agent)

Tạo file claude_desktop_config.json (hoặc tương tự cho IDE của bạn):

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "VIETQR_MERCHANT_ID": "YOUR_MERCHANT_ID",
        "VIETQR_API_KEY": "YOUR_API_KEY",
        "BANK_ACCOUNT": "1234567890",
        "BANK_CODE": "970436"  // Agribank, ví dụ
      }
    }
  }
}

Bạn sẽ lấy MERCHANT_ID và API_KEY từ trang https://agentpay.servicesai.vn/v1/docs.

Hướng dẫn code: Thu tiền từ đầu đến cuối

Dưới đây là ví dụ thực tế — một bot AI bán khoá học online:

Ví dụ 1: Tạo yêu cầu thanh toán

from agentpay_vn import AgentPayClient

# Khởi tạo client
client = AgentPayClient(
    merchant_id="YOUR_MERCHANT_ID",
    api_key="YOUR_API_KEY",
    bank_account="1234567890",
    bank_code="970436"
)

# Một học viên mới đăng ký khoá học Python
student_email = "student@example.com"
course_name = "Python Beginner"
course_price = 299000  # 299k VND

# Tạo yêu cầu thanh toán
payment_req = client.create_payment_request(
    merchant_ref=f"course_{int(time.time())}",  # ID duy nhất cho hóa đơn
    amount=course_price,
    description=f"Payment for {course_name}",
    customer_email=student_email,
    customer_phone="0901234567"
)

print(f"✅ Yêu cầu thanh toán tạo thành công!")
print(f"QR Code URL: {payment_req['qr_url']}")
print(f"Checkout URL: {payment_req['checkout_url']}")

# Gửi checkout URL cho học viên qua email
send_email_to_student(
    student_email,
    subject=f"Hoàn tất thanh toán khoá {course_name}",
    body=f"Vui lòng thanh toán tại: {payment_req['checkout_url']}"
)

Giải thích từng bước: - create_payment_request(): Tạo một yêu cầu thanh toán duy nhất, liên kết với merchant account của bạn. - merchant_ref: ID nội bộ để bạn track hoá đơn nào, khách nào. - amount: Số tiền VietQR sẽ thu (đơn vị VND). - qr_url: Link trỏ đến QR code (có thể render trong web/app). - checkout_url: Link gọi gọn cho khách click (mobile-friendly).

Ví dụ 2: Chờ xác nhận settlement & kích hoạt khoá học

import asyncio
from agentpay_vn import AgentPayClient

async def activate_course_on_payment(merchant_ref: str, student_id: str):
    """
    Chờ cho đến khi thanh toán được xác nhận, 
    rồi kích hoạt khoá học cho học viên.
    """
    client = AgentPayClient(
        merchant_id="YOUR_MERCHANT_ID",
        api_key="YOUR_API_KEY",
        bank_account="1234567890",
        bank_code="970436"
    )

    max_wait = 3600  # Chờ tối đa 1 giờ
    poll_interval = 5  # Kiểm tra mỗi 5 giây
    elapsed = 0

    print(f"⏳ Chờ xác nhận thanh toán cho {merchant_ref}...")

    while elapsed < max_wait:
        settlement = client.await_settlement(
            merchant_ref=merchant_ref,
            timeout=poll_interval
        )

        if settlement and settlement['status'] == 'confirmed':
            print(f"✅ Thanh toán xác nhận!")
            print(f"   Số tiền: {settlement['amount']} VND")
            print(f"   Thời gian: {settlement['settled_at']}")

            # Kích hoạt khoá học
            db.update_student_subscription(
                student_id=student_id,
                status='active',
                expiry_date=datetime.now() + timedelta(days=30)
            )

            # Gửi email chúc mừng
            send_email_to_student(
                student_email,
                subject="🎉 Khoá học đã được kích hoạt!",
                body="Bạn có thể bắt đầu học ngay bây giờ..."
            )

            return True

        elapsed += poll_interval
        await asyncio.sleep(poll_interval)

    print(f"❌ Hết thời gian chờ. Thanh toán chưa xác nhận.")
    return False

# Chạy async function
asyncio.run(activate_course_on_payment(
    merchant_ref="course_1234567890",
    student_id="student_123"
))

Giải thích: - await_settlement(): Hàm này chờ cho đến khi bank feed xác nhận tiền về account. Nó không block toàn bộ process, chỉ poll định kỳ. - Khi status == 'confirmed', có nghĩa tiền đã chuyển thành công vào tài khoản ngân hàng của bạn. - Bạn có thể chain hành động tiếp theo (update database, gửi email, webhook tới service khác).

Kịch bản đời thực: Quán cà phê tự động bán bằng bot

Tưởng tượng bạn có một quán cà phê nhỏ và muốn bán combo bằng chatbot Telegram:

Khách: "Mình muốn mua combo sáng + cà phê đen, tổng 45k"
Bot (AI): "Được! Combo Sáng Đen 45.000 VND. 
          Vui lòng quét QR này:
          [QR CODE]"

Khách: [scan QR bằng app ngân hàng] → [chuyển 45k]

Ngân hàng: [xác nhận giao dịch trong 2-3 giây]

Bot: "✅ Thanh toán thành công! 
     Số đơn hàng: #123456
     Vui lòng nhận ở quầy trong 5 phút."

Toàn bộ quy trình này có thể tự động hóa hoàn toàn bằng AgentPay + một bot Telegram:

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes
from agentpay_vn import AgentPayClient
import asyncio

client = AgentPayClient(...)
app = Application.builder().token("YOUR_TELEGRAM_TOKEN").build()

async def handle_order(update: Update, context: ContextTypes.DEFAULT_TYPE):
    chat_id = update.effective_chat.id
    amount = 45000  # Combo sáng + cà phê

    # Tạo QR
    payment = client.create_payment_request(
        merchant_ref=f"coffee_{chat_id}_{int(time.time())}",
        amount=amount,
        description="Combo Sáng + Cà Phê Đen"
    )

    # Gửi QR cho khách
    await context.bot.send_photo(
        chat_id=chat_id,
        photo=payment['qr_url'],
        caption=f"Vui lòng quét và chuyển {amount:,} VND"
    )

    # Chờ settlement async (không block bot)
    async def monitor_payment():
        settlement = await client.await_settlement(
            merchant_ref=payment['merchant_ref'],
            timeout=180  # 3 phút
        )
        if settlement and settlement['status'] == 'confirmed':
            await context.bot.send_message(
                chat_id=chat_id,
                text=f"✅ Thanh toán thành công!\nSố đơn: #123456\n"
                     f"Vui lòng nhận ở quầy."
            )

    asyncio.create_task(monitor_payment())

app.add_handler(CommandHandler("order", handle_order))
app.run_polling()

Nên & Không nên khi dùng AgentPay VN

✅ Nên	❌ Không nên
Dùng cho AI agent tự động	Mong chờ settlement tức thì (ngân hàng VN mất 2-5s)
Track từng transaction bằng `merchant_ref` duy nhất	Tái sử dụng cùng merchant_ref cho đơn hàng khác
Lưu `settled_at` & amount vào database để audit	Quên lưu settlement proof
Cấu hình timeout hợp lý (3-5 phút) cho polling	Set timeout quá ngắn (< 2s) dễ timeout
Test trên API sandbox trước khi production	Deploy trực tiếp lên production mà chưa test
Gửi email xác nhận SAU khi settlement confirmed	Gửi email trước khi tính tiền đã vào

Nâng cao: MCP Server & Multi-agent orchestration

Nếu bạn dùng Claude hay LLM khác qua MCP protocol, AgentPay cung cấp sẵn agentpay-mcp server. Điều này cho phép bạn định nghĩa AI agent phức tạp hơn:

# Terminal 1: Chạy MCP server
agentpay-mcp --merchant-id YOUR_ID --api-key YOUR_KEY --port 3000

# Terminal 2: LLM tương tác với MCP server
# (Claude hay custom LLM app sẽ call agentpay tools)

Các tools có sẵn trong MCP: - agentpay.create_payment_request - agentpay.get_payment_status - agentpay.await_settlement - agentpay.list_transactions

Bạn có thể viết prompt cho Claude như:

"Bạn là bot bán khoá học. Khi khách request mua, hãy dùng agentpay tools để tạo QR, gửi link, chờ xác nhận, rồi kích hoạt khoá."

Claude sẽ tự động chọn tool đúng lúc cần thiết, mà bạn không phải viết thêm code nào.

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

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

Tiền sẽ về trực tiếp vào tài khoản ngân hàng (BANK_ACCOUNT) mà bạn cấu hình. AgentPay không giữ tiền, chỉ là một lớp orchestration.

2. Phí bao nhiêu?

AgentPay VN là open-source (MIT license). Không có phí sử dụng SDK. Phí giao dịch (nếu có) là của VietQR / ngân hàng, không phải AgentPay.

3. Nếu khách scan QR nhưng không chuyển tiền thì sao?

await_settlement() sẽ timeout sau khoảng thời gian bạn set (mặc định 3600s). Bạn có thể gửi reminder cho khách, hoặc hủy đơn hàng tự động.

4. Tôi có thể dùng cho cửa hàng thực (POS) được không?

Có! AgentPay không bó buộc bạn chỉ dùng online. Bạn có thể tích hợp vào hệ thống POS, tạo QR động cho từng đơn hàng.

Tóm tắt nhanh

Cài: pip install agentpay-vn
Setup: Lấy Merchant ID & API Key từ docs, set biến môi trường
3 bước thu tiền: create_payment_request() → send_checkout_url() → await_settlement()
An toàn: Tiền về account thật, không giữ ở server trung gian
Tự động: AI agent tự xử lý từ đầu đến cuối, kích hoạt hành động tiếp theo
Linh hoạt: Dùng cho bot, POS, ecommerce, subscription — bất kỳ mô hình bán nào
Open-source: MIT license, có thể modify & deploy tuỳ ý

Bắt đầu ngay hôm nay

Bạn đã sẵn sàng để tự động hóa toàn bộ quy trình thu tiền? Đây là 3 bước tiếp theo:

Cài đặt SDK: bash pip install agentpay-vn
Lấy credentials & xem tài liệu: Truy cập https://agentpay.servicesai.vn/v1/docs
Tham khảo code & GitHub: https://github.com/phuocdu/agentpay-vn

Còn chần chừ gì nữa? Hãy cho AI agent của bạn "siêu năng lực" thu tiền VietQR! 🚀

Bắt đầu →

← Tất cả bài