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

2026-09-07 · AgentPay VN

aipythonvietqrmcpthanhtoan

Tình Huống Đau Đớn: Khi AI Gặp Tiền Mặt

Bạn vừa xây xong một con bot AI giáo dục, nó giải bài tập tốt lắm. Nhưng có một vấn đề:

Làm sao nó thu tiền từ học sinh?

Bạn không thể bảo học sinh gửi tiền vào một tài khoản bot — thật ngớ ngẩn. Cách thông thường? Tích hợp Stripe, Paypal, rồi chờ 5-10 ngày thanh toán. Hoặc tệ hơn: viết script tay để xử lý QR code, nhưng rồi bạn phải quản lý tiền — gánh nặng pháp lý, bảo mật, và rất dễ sai.

Nếu bot AI của bạn không cần giữ tiền, mà chỉ cần tạo QR code trỏ thẳng vào tài khoản merchant của bạn, rồi chờ xác nhận thanh toán? Đó chính là nơi AgentPay VN vào cuộc.

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

AgentPay VN là một SDK Python mã nguồn mở (MIT) giúp AI agent thực hiện thanh toán VietQR một cách đơn giản nhất có thể. Điểm nổi bật:

Thay vì bạn lo lắng về bảo mật, thanh toán, hay tuân thủ, AgentPay VN chỉ làm một việc duy nhất: tạo QR, nhận thông báo, xong.

Kiến Trúc Hoạt Động: 3 Bước Đơn Giản

Quy trình thanh toán của AgentPay VN chỉ có 3 bước cốt lõi:

Bước 1: Tạo Yêu Cầu Thanh Toán (Create Payment Request)

AI agent của bạn gọi create_payment_request() để tạo một invoice với số tiền cụ thể.

Bước 2: Gửi QR Checkout

Hệ thống trả lại một checkout_url — đây chính là QR code hoặc link thanh toán trỏ tới tài khoản merchant.

Bước 3: Chờ Xác Nhận Thanh Toán

AgentPay VN lắng nghe bank feed của bạn, khi tiền về → tự động xác nhận và kích hoạt callback.

Tất cả diễn ra không giữ tiền ở giữa — ngân hàng ghi nhận, bot biết.

Cài Đặt AgentPay VN: 5 Phút Là Xong

Trước tiên, chuẩn bị môi trường Python 3.8+:

# Cài đặt SDK từ pip
pip install agentpay-vn

# Nếu muốn dùng MCP server (cho Claude/Agent AI)
pip install agentpay-mcp

Đó là tất cả. Không cần config phức tạp.

Code Thực Hành: Thu Tiền Bằng Python

Dưới đây là ví dụ hoàn chỉnh để một bot AI thu tiền khoá học:

from agentpay_vn import PaymentClient, PaymentRequest
import asyncio
from datetime import datetime

# 1. Khởi tạo client (cần merchant_id và api_key từ AgentPay VN)
client = PaymentClient(
    merchant_id="YOUR_MERCHANT_ID",
    api_key="YOUR_API_KEY"
)

# 2. Tạo yêu cầu thanh toán cho một học sinh
async def collect_course_payment(student_name: str, course_price: int):
    # Tạo đối tượng yêu cầu thanh toán
    payment_req = PaymentRequest(
        amount=course_price,  # Giá tiền tính bằng VNĐ
        description=f"Khoá học Python - {student_name}",
        order_id=f"COURSE_{student_name}_{datetime.now().timestamp()}",
        return_url="https://your-site.com/success"
    )

    # 3. Gửi request tạo QR
    payment_response = await client.create_payment_request(payment_req)

    # payment_response chứa checkout_url (link QR hoặc mã QR)
    checkout_url = payment_response.checkout_url
    payment_id = payment_response.payment_id

    print(f"✓ QR tạo xong cho {student_name}")
    print(f"  Link thanh toán: {checkout_url}")
    print(f"  Payment ID: {payment_id}")

    return payment_id, checkout_url

# 4. Chờ xác nhận thanh toán
async def wait_for_settlement(payment_id: str, timeout_seconds: int = 300):
    """
    Lắng nghe bank feed, chờ tiền về.
    - timeout_seconds: chỉ chờ tối đa 5 phút (để tránh bot mắc kẹt)
    """
    settlement = await client.await_settlement(
        payment_id=payment_id,
        timeout=timeout_seconds
    )

    if settlement.confirmed:
        print(f"✅ Tiền đã về! Transaction: {settlement.transaction_id}")
        print(f"   Số tiền: {settlement.amount:,} VNĐ")
        print(f"   Ngân hàng xác nhận lúc: {settlement.confirmed_at}")
        return True
    else:
        print(f"❌ Hết timeout chờ thanh toán (hoặc đã bị hủy)")
        return False

# 5. Chạy end-to-end flow
async def main():
    student = "Nguyễn Văn A"
    course_fee = 299_000  # 299k VNĐ

    print(f"🤖 AI Agent bắt đầu thu tiền khoá học...\n")

    # Tạo QR
    payment_id, qr_url = await collect_course_payment(student, course_fee)

    print(f"\n⏳ Agent chờ học sinh quét QR...")
    input("(Nhấn Enter sau khi thanh toán xong)\n")

    # Chờ xác nhận
    success = await wait_for_settlement(payment_id)

    if success:
        print(f"\n🎉 Cấp quyền truy cập khoá học cho {student}!")
    else:
        print(f"\n⚠️  Gửi nhắc nhở thanh toán lại cho {student}")

# Chạy
if __name__ == "__main__":
    asyncio.run(main())

Giải thích từng phần:

Kết quả: Bot đã thu tiền của học sinh mà không một xu nào ở lại tay bot.

Tích Hợp MCP Server Cho Claude & AI Agent

Nếu bạn muốn Claude hoặc ChatGPT tương tác với AgentPay VN, dùng MCP server:

# Cài MCP server
pip install agentpay-mcp

# Chạy server (nghe trên port 5000 mặc định)
agentpay-mcp --port 5000

Trong Claude/Agent configuration, thêm:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "args": ["--port", "5000"],
      "env": {
        "AGENTPAY_MERCHANT_ID": "YOUR_MERCHANT_ID",
        "AGENTPAY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Sau đó, Claude có thể gọi trực tiếp:

Claude: "Tạo QR thanh toán 500k cho đơn hàng #12345"
→ MCP server xử lý → checkout_url trả lại → Claude gửi cho người dùng.

Ví Dụ Kịch Bản Thực Tế: Quán Cà Phê Tự Động

Hãy tưởng tượng bạn chạy một quán cà phê nhỏ với bot AI nhận đơn hàng:

Sáng: Khách vào, nói "Cho tôi cappuccino và croissant" → Bot nhận đơn, tính tiền: 75,000 VNĐ → Gọi create_payment_request(75_000, description="Cappuccino + Croissant") → QR hiển thị trên bảng menu → Khách quét → Tiền vào tài khoản quán ngay → Bot nhận callback → In bill tự động → Chuẩn bị cà phê

Không cần: POS machine đắt tiền, training nhân viên, lo lắng tiền mặt.

Chỉ cần: Bot, điện thoại, kết nối internet.

Bảng So Sánh: Các Lựa Chọn Thanh Toán

Yếu tố AgentPay VN Stripe PayPal Tự viết
Setup phức tạp Rất đơn giản (1 line) Trung bình (nhiều config) Trung bình Cực kỳ phức tạp
Giữ tiền Không bao giờ Có (2-3 ngày) Có (24h) Có (rủi ro lớn)
Hỗ trợ VietQR ✅ Có ❌ Không ❌ Không Tự xử (hay sai)
Mã nguồn mở ✅ MIT ❌ Không ❌ Không Tùy bạn
MCP integration ✅ Có ❌ Phải tự làm ❌ Phải tự làm Phải tự làm
Chi phí Miễn phí (open-source) 2.9% + 0.3$ mỗi giao dịch 3.49% + 0.49$ Phụ thuộc
Độ tin cậy Cao (bank feed) Rất cao Rất cao Thấp
Lý tưởng cho Bot AI, startup E-commerce lớn Quốc tế Không ai

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

✅ Nên Làm

❌ Không Làm

Xử Lý Lỗi & Edge Case

Thực tế không lúc nào hoàn hảo. Dưới đây là code xử lý tình huống đặc biệt:

from agentpay_vn import PaymentError, SettlementTimeout

async def robust_payment_flow(amount: int, description: str):
    try:
        # Tạo QR
        payment_req = PaymentRequest(
            amount=amount,
            description=description,
            order_id=f"ORDER_{int(datetime.now().timestamp())}"
        )
        response = await client.create_payment_request(payment_req)
        print(f"✓ QR created: {response.checkout_url}")

    except PaymentError as e:
        # Lỗi từ API (merchant_id sai, api_key hết hạn, v.v.)
        print(f"❌ API Error: {e}")
        return None

    payment_id = response.payment_id

    try:
        # Chờ thanh toán
        settlement = await client.await_settlement(payment_id, timeout=300)

        if settlement.confirmed:
            print(f"✅ Payment confirmed: {settlement.amount:,} VNĐ")
            return settlement
        else:
            print(f"⚠️ Settlement failed or cancelled")
            return None

    except SettlementTimeout:
        # User quên thanh toán hoặc mạng bị gián đoạn
        print(f"⏱️ Payment timeout. Remind user to pay or check later.")
        # Lưu payment_id, kiểm tra lại sau
        save_to_db(payment_id, status="PENDING")
        return None

    except Exception as e:
        print(f"❌ Unexpected error: {e}")
        return None

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

Q1: "Tiền sẽ về tài khoản của tôi mất bao lâu?"

A: AgentPay VN nhận thông báo từ bank feed trong vòng 30-120 giây sau khi bạn chuyển khoản xong. Chính ngân hàng thì thường xác nhận trong 1-5 phút. Bot bạn có thể hoạt động mà không cần chờ ngân hàng.

Q2: "Có phí gì không? Có bị trừ hoa hồng không?"

A: AgentPay VN miễn phí (mã nguồn mở). Bạn chỉ bị trừ phí chuyển khoản bình thường của ngân hàng (thường là 0-5k VNĐ tùy bank). Không có hoa hồng thêm.

Q3: "Làm sao nếu user thanh toán sai số tiền?"

A: Settlement callback sẽ chứa số tiền thực tế (settlement.amount). Bạn có thể so sánh với expected amount:

if settlement.amount != expected_amount:
    print(f"Mismatch: expected {expected_amount}, got {settlement.amount}")
    # Log, gửi cảnh báo, hoặc yêu cầu thanh toán lại

Q4: "Có hỗ trợ lập kế hoạch thanh toán không (ví dụ: trả góp)?"

A: Hiện tại AgentPay VN không có built-in subscription. Nhưng bạn có thể tự xây: lưu payment_id vào database, schedule job tạo QR mới vào các kỳ hạn sau. Hoặc góp ý lên GitHub!

Tóm Tắt Nhanh

Bước Tiếp Theo: Hành Động Ngay

Bạn đã hiểu rõ cách hoạt động. Giờ đến lúc bắt tay vào làm:

  1. Cài đặt SDK: pip install agentpay-vn
  2. Lấy Merchant ID & API Key: Đăng ký tại https://agentpay.servicesai.vn/v1/docs
  3. Copy-paste ví dụ code ở trên, chạy test.
  4. Tích hợp vào bot của bạn.
  5. Deploy & kiếm tiền.

Không biết bắt đầu từ đâu? Đọc tài liệu đầy đủ hoặc xem mã nguồn trên GitHub — đều dễ hiểu.

Còn câu hỏi? Mở Issue trên GitHub, team AgentPay VN rất tán thành feedback.

Hãy nhớ: Thế giới không còn cần bot AI chỉ biết trò chuyện. Thế giới cần bot kiếm tiền. AgentPay VN giúp bạn làm điều đó — một cách đơn giản, an toàn, và minh bạch.

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

Bắt đầu →

← Tất cả bài