Hướng dẫn: Tích hợp AI Agent thu tiền VietQR bằng Python

2026-09-20 · AgentPay VN

Tình huống: Chatbot bán khoá học nhưng không thể nhận tiền

Bạn vừa xây dựng một chatbot AI bán khoá học lập trình trực tuyến. Bot có thể tư vấn, giải đáp câu hỏi, thậm chí gợi ý khoá học phù hợp. Nhưng khi khách hàng sẵn sàng thanh toán, lúc ấy bot lại "ngơ ngác"—phải dừng cuộc trò chuyện, yêu cầu khách vào website riêng, hay tệ hơn là đưa số tài khoản ngân hàng để chuyển khoản thủ công. Kết quả? Nhiều khách tiềm năng bỏ đi, doanh số giảm sút.

Vấn đề này không phải do bot không "thông minh" đủ, mà do nó thiếu khả năng xử lý thanh toán trực tiếp. Nếu bot có thể tự tạo mã QR thanh toán, gửi cho khách, và tự động xác nhận khi tiền về—tất cả trong cùng một cuộc chat—thì trải nghiệm khách hàng sẽ hoàn toàn khác.

Có cách nào để làm được điều này không? Có, đó chính là AgentPay VN.

AgentPay VN là gì? Tại sao lại quan trọng?

AgentPay VN là một open-source SDK Python (giấy phép MIT) kèm MCP server cho phép bất kỳ AI agent nào cũng có thể:

1. Tạo yêu cầu thanh toán VietQR trực tiếp từ code Python
2. Gửi checkout link tới khách hàng (qua Telegram, email, hay nhắn tin)
3. Tự động xác nhận khi tiền đã về tài khoản ngân hàng của bạn

Đặc biệt quan trọng: AgentPay KHÔNG giữ tiền. Mã QR luôn chỉ vào tài khoản ngân hàng thực của bạn; khi khách thanh toán, tiền về trực tiếp vào ngân hàng. Sau đó, một "bank feed" từ ngân hàng sẽ xác nhận với bot của bạn rằng khoản thanh toán đã hoàn tất.

Quy trình thanh toán 3 bước đơn giản

Toàn bộ luồng thanh toán được thiết kế để AI agent có thể thực hiện mà không cần can thiệp con người:

Bước 1: Tạo yêu cầu thanh toán Bot gọi hàm create_payment_request() với số tiền, mô tả sản phẩm, và ID khách hàng.

Bước 2: Gửi checkout URL Bot lấy link thanh toán từ bước 1 và gửi tới khách qua email, Telegram, hay hiển thị trực tiếp trong chat.

Bước 3: Chờ xác nhận Bot gọi await_settlement() để chờ bank feed xác nhận thanh toán. Khi tiền về, bot tự động cấp quyền truy cập khoá học, gửi tài liệu, hay kích hoạt tính năng tiếp theo.

Cài đặt và khởi chạy

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

Mở terminal và chạy:

pip install agentpay-vn

Đó là tất cả. Không cần cấu hình phức tạp, không cần tạo tài khoản trung gian, không cần API key từ bên thứ ba.

Bước 2: Cấu hình MCP Server (nếu dùng Claude AI)

Nếu bạn muốn tích hợp với Claude hoặc các AI model khác qua MCP protocol, thêm cấu hình sau vào file config của Claude:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "args": []
    }
  }
}

Cấu hình này cho phép Claude gọi các hàm thanh toán của AgentPay mà không cần viết code thêm.

Bước 3: Thiết lập thông tin tài khoản

Tạo file .env hoặc biến môi trường với thông tin ngân hàng của bạn:

BANK_ACCOUNT_NUMBER=1234567890
BANK_ACCOUNT_NAME=Nguyen Van A
BANK_ID=970403

Bank ID là mã định danh ngân hàng (ví dụ: 970403 là VietcomBank). Danh sách đầy đủ có ở docs.

Ví dụ thực tế: Bot bán khoá học lập trình

Hãy tưởng tượng bạn chạy một bot Telegram hỗ trợ bán khoá học "Python từ 0". Quy trình như sau:

1. Khách chat với bot, hỏi về nội dung khoá học.
2. Bot tư vấn xong, khách quyết định mua (giá 199,000 VNĐ).
3. Bot tạo yêu cầu thanh toán và gửi mã QR + link: - "Vui lòng quét mã QR này hoặc bấm link để thanh toán: [checkout_url]"
4. Khách quét QR bằng app ngân hàng, xác nhận thanh toán.
5. Tiền về tài khoản bot owner; bank feed gửi tín hiệu xác nhận.
6. Bot tự động: - Cấp quyền truy cập khoá học. - Gửi link tải tài liệu lập trình. - Mời khách vào group Discord học tập.

Kết quả: Khách hàng mua, học, và nhận hỗ trợ—tất cả trong 5 phút, mà không cần bot owner can thiệp.

Hướng dẫn code từng bước

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

from agentpay_vn import PaymentRequest, create_payment_request

# Tạo yêu cầu thanh toán
payment = create_payment_request(
    amount=199000,                    # Số tiền VNĐ
    description="Khoá học Python từ 0 - Khóa 2024",  # Mô tả sản phẩm
    customer_id="customer_123",       # ID khách hàng (để theo dõi)
    merchant_name="Tech Learning Hub" # Tên cửa hàng
)

# Lấy thông tin quan trọng
checkout_url = payment.checkout_url  # Link để gửi cho khách
qr_code_data = payment.qr_code       # Dữ liệu QR (có thể mã hóa thành hình)
payment_id = payment.id              # ID giao dịch

print(f"Gửi link này cho khách: {checkout_url}")
print(f"ID giao dịch: {payment_id}")

Giải thích: - amount: Số tiền khách cần thanh toán (đơn vị: đồng Việt Nam). - description: Dòng chữ mô tả sản phẩm—khách sẽ thấy trên app ngân hàng khi thanh toán. - customer_id: Mã định danh khách (của bạn), dùng để liên kết với dữ liệu khách trong hệ thống của bạn (cơ sở dữ liệu, CRM, v.v.). - merchant_name: Tên cửa hàng/công ty của bạn.

Hàm create_payment_request() trả về object chứa checkout_url (link thanh toán) và qr_code (mã QR dưới dạng string).

Ví dụ 2: Chờ xác nhận và xử lý sau khi thanh toán

import asyncio
from agentpay_vn import await_settlement

async def process_payment(payment_id, customer_id):
    """
    Chờ thanh toán hoàn tất, sau đó cấp quyền truy cập khóa học.
    """
    try:
        # Chờ bank feed xác nhận thanh toán (timeout 5 phút)
        settlement = await await_settlement(
            payment_id=payment_id,
            timeout_seconds=300
        )

        # Nếu chuyến tiền đã đến
        if settlement.confirmed:
            print(f"✅ Thanh toán xác nhận: {settlement.amount} VNĐ")
            print(f"Thời gian: {settlement.timestamp}")

            # Cấp quyền cho khách
            grant_course_access(customer_id)
            send_welcome_email(customer_id)

            return {"status": "success", "message": "Khách hàng đã có quyền truy cập khoá học"}
        else:
            print(f"⏳ Chưa nhận được xác nhận từ ngân hàng")
            return {"status": "pending", "message": "Vui lòng chờ"}

    except TimeoutError:
        print("⏰ Timeout: Khách chưa thanh toán trong 5 phút")
        return {"status": "timeout", "message": "Thanh toán không được hoàn tất"}

# Sử dụng
asyncio.run(process_payment(payment_id="pay_xyz", customer_id="customer_123"))

Giải thích: - await_settlement() là hàm async (bất đồng bộ), nghĩa là nó sẽ chờ trong nền mà không chặn chương trình chính. - timeout_seconds=300: Nếu 5 phút mà khách vẫn chưa thanh toán, hàm sẽ dừng lại. - settlement.confirmed: Kiểm tra xem tiền đã về hay chưa. - Sau khi thanh toán được xác nhận, bạn có thể gọi các hàm như grant_course_access() để cấp quyền truy cập.

Tích hợp với Claude AI (MCP)

Nếu bạn dùng Claude làm AI agent, có thể cấu hình MCP server để Claude gọi AgentPay trực tiếp:

{
  "mcpServers": {
    "agentpay-vn": {
      "command": "agentpay-mcp",
      "args": [],
      "env": {
        "BANK_ACCOUNT_NUMBER": "1234567890",
        "BANK_ACCOUNT_NAME": "Nguyen Van A",
        "BANK_ID": "970403"
      }
    }
  }
}

Sau khi cấu hình, Claude sẽ có sẵn các tool: - create_payment – tạo yêu cầu thanh toán - check_settlement – kiểm tra trạng thái giao dịch - get_payment_status – lấy tình trạng thanh toán chi tiết

Claude sẽ tự động gọi các tool này khi cần mà không cần bạn viết code.

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

Kịch bản thực tế: Quán cà phê bán online

Giả sử bạn chạy quán cà phê và muốn bán combo cà phê online. Bot Zalo của bạn hoạt động như sau:

Khách: "Mình muốn mua combo sáng (cà phê + bánh mì). Bao nhiêu tiền?"

Bot: "Combo sáng ngon lành - 49.900 VNĐ thôi. Bạn có muốn đặt không?"

Khách: "Được, mình mua"

Bot: "Cảm ơn! Vui lòng quét mã QR này để thanh toán:
[Hiển thị mã QR]
Hoặc bấm link: https://checkout.agentpay-vn.com/pay/xyz123

Khi thanh toán xong, mình sẽ xác nhận đơn và giao hôm nay 9-11h sáng."

(Khách quét QR, thanh toán)

Bot: "✅ Thanh toán thành công! Đơn hàng của bạn:
- Cà phê đen đá
- Bánh mì thịt nướng
- Tổng: 49.900 VNĐ

Chúng mình sẽ giao vào lúc 10h sáng. Cảm ơn bạn!"

Toàn bộ quy trình diễn ra trong Zalo mà không cần khách rời khỏi app.

Bảng so sánh: AgentPay vs phương pháp khác

Những câu hỏi thường gặp (FAQ)

Q1: Tiền sẽ về đâu khi khách thanh toán?

A: Tiền về thẳng vào tài khoản ngân hàng của bạn (số tài khoản mà bạn đã cấu hình). AgentPay không giữ tiền, chỉ tạo mã QR chỉ vào tài khoản thực của bạn.

Q2: Nếu khách thanh toán sai số tiền thì sao?

A: Bạn nên kiểm tra settlement.amount trong code để so sánh với số tiền yêu cầu. Nếu không khớp, có thể từ chối cấp quyền truy cập hoặc yêu cầu khách thanh toán thêm.

Q3: Có mất phí gì không?

A: AgentPay VN là open-source và miễn phí. Tuy nhiên, ngân hàng của bạn có thể tính phí chuyển tiền hoặc phí dịch vụ (tùy từng ngân hàng). Điều này không liên quan đến AgentPay.

Q4: Có thể dùng với các AI platform khác ngoài Claude không?

A: Có thể! SDK Python của AgentPay hoạt động với bất kỳ bot Python nào (Telegram, Discord, Zalo, v.v.). MCP server chủ yếu dùng cho Claude, nhưng SDK gốc thì phổ quát.

Tóm tắt nhanh

• AgentPay VN là SDK Python + MCP server giúp AI agents thu tiền VietQR một cách tự động.
• Không giữ tiền: Mã QR chỉ vào tài khoản ngân hàng thực của bạn; tiền về trực tiếp.
• 3 bước đơn giản: create_payment_request() → gửi checkout_url → await_settlement().
• Cài đặt dễ: Chỉ cần pip install agentpay-vn.
• Sử dụng được ngay: Không cần API key từ bên thứ ba, không cần tạo tài khoản trung gian.
• Tích hợp AI tốt: Hỗ trợ MCP cho Claude, và có thể dùng với bất kỳ bot Python nào.
• An toàn: Open-source (MIT), code công khai, bạn có thể kiểm tra từng dòng.
• Trải nghiệm khách tuyệt vời: Khách không cần rời khỏi chat, thanh toán xong là có quyền truy cập ngay.

Bước tiếp theo: Bắt đầu ngay hôm nay

Bạn sẵn sàng để AI agent của mình có thể tự thu tiền? Thực hiện 3 bước này:

1. Cài đặt: pip install agentpay-vn
2. Đọc docs: https://agentpay.servicesai.vn/v1/docs
3. Clone ví dụ: https://github.com/phuocdu/agentpay-vn

Có thắc mắc gì? Mở issue trên GitHub hoặc tham khảo docs. Cộng đồng AgentPay VN sẵn sàng giúp bạn.

Happy coding! 🚀

Bắt đầu →

← Tất cả bài