Tự động thu tiền VietQR cho AI agent: Hướng dẫn AgentPay VN

2026-06-22 · AgentPay VN

agentpayvietqrpythonai-agentmcp

Bài toán: Tại sao AI agent của bạn lại cần thu tiền?

Tưởng tượng: Bạn xây dựng một chatbot bán khoá học trực tuyến. Khách hàng gõ "Mua khoá Python nâng cao", bot lập tức tạo hóa đơn, gửi mã QR thanh toán, và... rồi đó? Tiền đâu rồi? Nếu sử dụng Stripe, bạn đối mặt với:

Chi phí quốc tế cao: 3,9% + 0,30 USD per transaction – cắt cơm của người Việt.
Thủ tục phức tạp: Xác minh tài khoản nước ngoài, chờ phê duyệt, rắc rối pháp lý.
Độ trễ thanh toán: Tiền về tài khoản sau 2-3 ngày.
Không linh hoạt: Khó tích hợp vào logic tự động của AI agent.

AgentPay VN ra đời để giải quyết chính xác bài toán này – giúp AI agent tự động thu tiền VietQR mà không cần trung gian, không giữ tiền, tiền về ngay tức khắc.

AgentPay VN là gì? Nguyên lý hoạt động

Khác biệt so với ví dụ Stripe:

AgentPay VN là một SDK Python open-source (MIT) + MCP server cho phép:

AI agent tạo request thanh toán → hệ thống phát sinh mã QR VietQR.
Gửi đường link checkout trực tiếp cho khách hàng (không qua cổng trung gian).
QR code trỏ thẳng tài khoản ngân hàng của bạn – AgentPay KHÔNG giữ tiền.
Xác nhận settlement tự động qua bank feed – bot biết tiền đã về.

Ưu điểm: - ✅ Miễn phí (open-source) - ✅ Không commission, không giữ tiền - ✅ Thanh toán VietQR chuẩn Việt Nam (VCB, MB, ACB, Techcombank, ...) - ✅ Tích hợp trực tiếp vào AI agent qua MCP - ✅ Xác nhận thanh toán tự động qua bank feed

Cài đặt AgentPay VN: Bước đầu tiên

1. Cài đặt SDK Python

pip install agentpay-vn

Khiến SDK này được cài đặt, bạn sẽ có quyền truy cập các hàm core như create_payment_request(), send_checkout_url(), và await_settlement().

2. Cài đặt MCP Server (tùy chọn, nhưng khuyến khích)

Nếu bạn muốn dùng Claude hoặc các AI client khác:

pip install agentpay-mcp

Sau đó khởi động MCP server:

agentpay-mcp --port 8000

Của Claude, cấu hình trong claude_desktop_config.json:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "args": ["--port", "8000"],
      "env": {
        "AGENTPAY_BANK_ACCOUNT": "your_account_number",
        "AGENTPAY_BANK_NAME": "VCB",
        "AGENTPAY_ACCOUNT_HOLDER": "Your Name"
      }
    }
  }
}

3. Lấy thông tin ngân hàng

Bạn cần chuẩn bị: - Số tài khoản ngân hàng (ví dụ: 1234567890) - Mã ngân hàng (ví dụ: VCB, MB, ACB, TCB) - Tên chủ tài khoản (ví dụ: NGUYEN VAN A)

Luồng thanh toán 3 bước: Ví dụ kịch bản thực tế

Kịch bản: Bot bán khoá học AI cho startup

Giả sử bạn chạy một chatbot bán khoá "Xây dựng AI agent với Python" giá 500.000 VND.

Bước 1: Tạo payment request

from agentpay_vn import create_payment_request

# Khách hàng gõ: "Mua khoá AI agent"
payment_req = create_payment_request(
    amount=500000,  # VND
    description="Khóa học: Xây dựng AI agent với Python",
    order_id="COURSE_001_2024",
    customer_name="Phạm Minh Tuấn",
    customer_phone="0987654321",
    merchant_account="1234567890",
    merchant_bank="VCB",
    merchant_name="Your Company Ltd."
)

print(f"QR Code: {payment_req['qr_code_url']}")
print(f"Checkout URL: {payment_req['checkout_url']}")

Giải thích từng dòng: - amount=500000: Số tiền tính bằng VND. - description: Nội dung chuyển khoản (khách hàng sẽ thấy trong app ngân hàng). - order_id: ID đơn hàng duy nhất của bạn (để tra cứu sau). - customer_*: Thông tin khách hàng. - merchant_*: Thông tin tài khoản ngân hàng của bạn.

Kết quả: Trả về một URL chứa mã QR VietQR.

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

# Bot gửi thông báo cho khách hàng
checkout_url = payment_req['checkout_url']
message = f"""
✅ Đơn hàng của bạn đã được tạo!
Giá: 500.000 VND
Thời hạn thanh toán: 15 phút

👉 Thanh toán ngay: {checkout_url}

Hoặc quét mã QR bên dưới:
{payment_req['qr_code_url']}
"""

# Gửi qua Telegram, Zalo, Email, ...
send_to_customer(message)

Bước 3: Chờ xác nhận settlement

from agentpay_vn import await_settlement

# Lắng nghe xác nhận từ bank feed
def process_payment(order_id):
    settlement = await_settlement(
        order_id=order_id,
        timeout=900  # Chờ tối đa 15 phút
    )

    if settlement['status'] == 'confirmed':
        print(f"✅ Thanh toán thành công!")
        print(f"Số tiền: {settlement['amount']} VND")
        print(f"Ngân hàng: {settlement['bank']}")
        print(f"Thời gian: {settlement['timestamp']}")

        # Cấp quyền truy cập khoá học cho khách hàng
        grant_course_access(customer_email, course_id="COURSE_001")
        send_confirmation_email(customer_email)
    else:
        print("❌ Thanh toán thất bại hoặc hết thời gian")
        send_payment_reminder_email(customer_email)

# Chạy trong background
process_payment(order_id="COURSE_001_2024")

Giải thích: - timeout=900: Chờ tối đa 15 phút để khách hàng thanh toán. - settlement['status']: Sẽ trả về 'confirmed' nếu tiền đã vào tài khoản. - Khi xác nhận, bot tự động cấp quyền truy cập khoá học.

Tích hợp với Claude qua MCP

Nếu bạn dùng Claude làm AI agent, bạn có thể cho phép Claude tự gọi các hàm AgentPay:

# Giả sử Claude muốn bán sản phẩm
# Claude sẽ có quyền gọi hàm này qua MCP:

# tool: create_vietqr_payment
# input: { "amount": 250000, "description": "Sản phẩm XYZ" }
# output: { "checkout_url": "...", "qr_code_url": "..." }

Cấu hình MCP server (file agentpay_mcp_config.json):

{
  "tools": [
    {
      "name": "create_vietqr_payment",
      "description": "Tạo yêu cầu thanh toán VietQR mới",
      "input_schema": {
        "type": "object",
        "properties": {
          "amount": { "type": "number", "description": "Số tiền VND" },
          "description": { "type": "string", "description": "Mô tả đơn hàng" },
          "customer_name": { "type": "string" },
          "customer_phone": { "type": "string" }
        },
        "required": ["amount", "description"]
      }
    },
    {
      "name": "check_payment_status",
      "description": "Kiểm tra trạng thái thanh toán",
      "input_schema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" }
        },
        "required": ["order_id"]
      }
    }
  ]
}

Các trường hợp sử dụng thực tế

1. Quán cà phê thông minh

Khách gọi chatbot: "2 cà phê đen, 1 bánh mỳ"
Bot tính toán: 65.000 VND
Gửi QR VietQR cho khách
Khi thanh toán confirmed → máy pha cà phê tự động nhận order
Khách nhận hàng, bot tự động xóa order

2. Dịch vụ gọi xe AI

Khách đặt chuyến đi từ A → B
Bot tính giá: 125.000 VND
Tạo payment request
Chỉ khi thanh toán confirmed → bot confirm chuyến đi
Tài xế nhận order

3. Platform khóa học online

Học viên duyệt khóa học
Bot hiển thị giá + nút "Mua ngay"
Create payment request → gửi checkout URL
Settlement confirmed → cấp quyền truy cập khoá
Gửi email + link tài liệu

Nên làm / Không nên làm

Nên làm ✅	Không nên làm ❌
Sử dụng `order_id` duy nhất cho mỗi giao dịch	Tái sử dụng `order_id` cũ
Cài đặt `timeout` phù hợp (15-30 phút)	Để `timeout` quá ngắn (<5 phút)
Log tất cả payment request để audit	Không lưu lịch sử thanh toán
Xác minh `merchant_account` trước khi deploy	Để thông tin tài khoản sai
Gửi confirmation email sau settlement	Gửi confirmation trước khi xác nhận
Sử dụng HTTPS để bảo vệ QR code URL	Gửi QR code qua HTTP
Test với môi trường staging trước	Deploy trực tiếp lên production

Lỗi thường gặp & Xử lý

# Lỗi 1: Bank feed chưa kết nối
try:
    settlement = await_settlement(order_id="ORDER_001", timeout=900)
except BankFeedNotConnectedError:
    print("⚠️ Bank feed chưa được kết nối")
    print("Hãy cấu hình bank feed trong settings AgentPay")

# Lỗi 2: Số tiền không khớp
if settlement['amount'] != expected_amount:
    print(f"⚠️ Số tiền không khớp: {settlement['amount']} vs {expected_amount}")
    # Log để audit, không cấp quyền truy cập
    log_suspicious_transaction(settlement)

# Lỗi 3: Timeout (khách hàng không thanh toán)
except PaymentTimeoutError:
    print("❌ Hết thời gian thanh toán")
    # Gửi nhắc nhở lại
    send_payment_reminder(customer_email, checkout_url)

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

Câu 1: AgentPay có giữ tiền không?

Không. Tiền đi thẳng vào tài khoản ngân hàng của bạn qua VietQR. AgentPay chỉ là SDK để tạo QR code và xác nhận settlement qua bank feed.

Câu 2: Làm sao để biết tiền đã về tài khoản?

Qua await_settlement() function, nó lắng nghe bank feed từ ngân hàng. Khi ngân hàng báo về có giao dịch matching với order_id → hàm trả về status='confirmed'.

Câu 3: Có thể tích hợp với Telegram, Zalo không?

Có! Bạn gửi checkout_url hoặc qr_code_url qua API của Telegram/Zalo. Khách hàng nhấn vào → tự động mở ứng dụng ngân hàng để thanh toán.

Câu 4: Nếu khách hàng thanh toán sai số tiền, sao?

AgentPay so sánh settlement['amount'] với expected_amount. Nếu không khớp, hàm sẽ báo lỗi hoặc trả về status='mismatch'. Bạn có thể gọi API ngân hàng để hoàn tiền.

Tóm tắt nhanh

🚀 AgentPay VN = SDK Python open-source để AI agent tự động thu tiền VietQR
💰 Không commission, không giữ tiền – tiền về tài khoản ngân hàng ngay lập tức
🔧 Cài đặt dễ: pip install agentpay-vn
📱 3 bước chính: create_payment_request() → gửi URL → await_settlement()
🤖 Tích hợp MCP để dùng với Claude hoặc AI client khác
🏦 Hỗ trợ tất cả ngân hàng tham gia VietQR (VCB, MB, ACB, Techcombank, ...)
📊 Bank feed xác nhận settlement tự động → bot biết thanh toán rồi

Hành động tiếp theo

Bước 1: Cài đặt ngay hôm nay

pip install agentpay-vn

Bước 2: Đọc tài liệu chi tiết

Truy cập: https://agentpay.servicesai.vn/v1/docs

Bước 3: Fork & star GitHub

https://github.com/phuocdu/agentpay-vn

Bước 4: Bắt đầu xây dựng

Viết bot bán sản phẩm đầu tiên của bạn với VietQR – không Stripe, không phí quốc tế, không phức tạp.

Với AgentPay VN, AI agent của bạn không chỉ trò chuyện – mà còn kiếm tiền cho bạn! 💵

Bắt đầu →

← Tất cả bài