Hướng dẫn: Tích hợp VietQR vào AI Agent Python

2026-06-23 · AgentPay VN

aipythonvietqrmcpthanh toán

Vấn đề: AI Agent của bạn cần thu tiền nhưng không biết bắt đầu từ đâu

Hãy tưởng tượng bạn vừa xây dựng một bot AI bán khóa học online, hoặc một chatbot hỗ trợ đặt hàng cho quán cà phê. Bot hoạt động tốt, khách hàng yêu thích, nhưng khi đến lúc nhận tiền… bạn lại phải dừng lại và làm thủ công. Phải gửi link thanh toán bằng tay, chờ xác nhận bank, rồi cập nhật trạng thái đơn hàng. Những công việc repetitive này không chỉ tốn thời gian mà còn dễ sai sót.

Câu hỏi đặt ra: Làm sao để AI agent tự động xử lý toàn bộ luồng thanh toán VietQR từ tạo hoá đơn đến xác nhận tiền vào tài khoản ngân hàng?

Chính vì vậy, AgentPay VN ra đời — một Python SDK mã nguồn mở (MIT license) cho phép các AI agent thu tiền VietQR mà không bao giờ phải "giữ tiền".

AgentPay VN là gì? Hiểu rõ kiến trúc

AgentPay VN gồm hai thành phần chính:

1. Python SDK (agentpay-vn) - Thư viện nhẹ, dễ cài đặt: pip install agentpay-vn - Cung cấp các hàm để tạo yêu cầu thanh toán, tạo QR code VietQR - Không bao giờ xử lý tiền trực tiếp — QR code luôn trỏ thẳng vào tài khoản ngân hàng của merchant

2. MCP Server (agentpay-mcp) - Model Context Protocol server tích hợp với Claude và các AI model khác - Cho phép agent gọi các hàm thanh toán như gọi tool thông thường - Tự động quản lý trạng thái thanh toán theo bank feed

Nguyên lý hoạt động: - Merchant khởi tạo yêu cầu thanh toán qua SDK - Agent tạo QR code VietQR (QR trỏ vào ngân hàng merchant) - Agent gửi link thanh toán cho customer - Bank tự động gửi notification khi tiền vào tài khoản - Agent xác nhận settlement và tiếp tục quy trình kinh doanh

Cài đặt và kết nối với AI Agent

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

pip install agentpay-vn

Thế là xong! Không cần cấu hình database hay server riêng. SDK chạy hoàn toàn trên máy của bạn.

Bước 2: Kết nối MCP Server với Claude

Nếu bạn sử dụng Claude Desktop hoặc Claude API, thêm cấu hình MCP vào file claude_desktop_config.json (hoặc tương đương):

{
  "mcpServers": {
    "agentpay-vn": {
      "command": "python",
      "args": ["-m", "agentpay_mcp.server"],
      "env": {
        "BANK_ACCOUNT": "1234567890",
        "BANK_CODE": "970418",
        "MERCHANT_NAME": "Quán Cà Phê Thắng"
      }
    }
  }
}

Lưu ý: - BANK_ACCOUNT: số tài khoản ngân hàng của bạn - BANK_CODE: mã ngân hàng (ví dụ: 970418 = Techcombank) - MERCHANT_NAME: tên hiển thị trên QR code

Sau khi restart Claude, agent sẽ có khả năng gọi các function thanh toán.

Luồng 3 dòng: Từ yêu cầu đến xác nhận tiền

Toàn bộ quy trình thanh toán AgentPay VN có thể tóm gọn thành 3 bước chính:

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

from agentpay_vn import PaymentClient

# Khởi tạo client
client = PaymentClient(
    bank_account="1234567890",
    bank_code="970418",
    merchant_name="Quán Cà Phê Thắng"
)

# Tạo yêu cầu thanh toán
payment = client.create_payment_request(
    amount=250000,  # 250.000 VND
    description="Mua 1 cà phê Arabica + 1 bánh Croissant",
    order_id="ORD-20250115-001",
    customer_name="Nguyễn Văn A",
    customer_phone="0912345678"
)

print(f"QR Code URL: {payment.qr_url}")
print(f"Checkout URL: {payment.checkout_url}")
print(f"Reference: {payment.reference}")

Giải thích: - amount: số tiền cần thu (tính bằng VND) - description: mô tả đơn hàng hiển thị trên QR - order_id: mã đơn hàng duy nhất (để tracking) - Hàm trả về object chứa QR code URL và checkout URL

Bước 2: Gửi link thanh toán cho customer

Agent sẽ gửi payment.checkout_url cho customer qua: - Tin nhắn Messenger / WhatsApp - Email - Hiển thị QR code trực tiếp trên màn hình kiosk

# Ví dụ: gửi qua in ra console (trong thực tế dùng API chat/email)
print(f"Customer vui lòng quét QR hoặc bấm vào link này:")
print(f"Link: {payment.checkout_url}")
print(f"Mã tham chiếu: {payment.reference}")

Bước 3: Chờ xác nhận settlement (`await_settlement`)

import asyncio
from agentpay_vn import PaymentClient

client = PaymentClient(
    bank_account="1234567890",
    bank_code="970418",
    merchant_name="Quán Cà Phê Thắng"
)

async def wait_for_payment(reference, timeout=600):
    """
    Chờ xác nhận thanh toán từ bank feed.
    timeout: thời gian chờ tối đa (giây)
    """
    settlement = await client.await_settlement(
        reference=reference,
        timeout=timeout
    )

    if settlement:
        print(f"✓ Thanh toán thành công!")
        print(f"  Số tiền: {settlement.amount} VND")
        print(f"  Thời gian: {settlement.timestamp}")
        print(f"  Message: {settlement.message}")
        return settlement
    else:
        print(f"✗ Timeout: Khách hàng chưa thanh toán sau 10 phút")
        return None

# Sử dụng trong agent
result = await wait_for_payment(reference="payment_ref_123")
if result:
    # Agent tiếp tục quy trình (gửi hóa đơn, cập nhật kho, v.v.)
    print("Gửi email xác nhận và cập nhật đơn hàng...")

Giải thích: - await_settlement() là hàm async (không chặn thread chính) - Nó poll bank feed mỗi 2-3 giây để kiểm tra tiền vào - Trả về object Settlement chứa chi tiết thanh toán - Nếu timeout, trả về None (customer không thanh toán)

Kịch bản thực tế: Bot bán khóa học online

Môi trường: Bạn có một chatbot bán khóa học "Python Pro" giá 990.000 VND.

Luồng tương tác:

Customer: "Tôi muốn mua khóa học Python Pro"
Bot (Agent): "Quá tuyệt vời! Khóa học này có nội dung [chi tiết]. Giá là 990.000 VND. Bạn có muốn thanh toán không?"
Customer: "Có, tôi thanh toán"
Bot thực thi: - Tạo payment request với amount=990000 - Lấy QR code và gửi: "Vui lòng quét QR hoặc bấm [link]..." - Chờ settlement (timeout 10 phút)
Customer quét QR VietQR trên điện thoại, chuyển tiền
Bank gửi notification → AgentPay nhận qua bank feed
Bot phát hiện settlement: - Lập tức gửi link download khóa học - Cấp access vào trang học trực tuyến - Gửi email xác nhận hoá đơn - Cập nhật database students

Lợi ích: - Customer không phải nhập bank account hay SWIFT code phức tạp - Bot hoàn toàn tự động, không cần người quản lý hỗ trợ - Tiền vào tài khoản ngân hàng thực của bạn trong vòng 5-10 phút - Khóa học được cấp ngay, tăng conversion rate

Nên làm gì / Không nên làm gì khi dùng AgentPay VN

✓ NÊN	✗ KHÔNG NÊN
Lưu `order_id` và `reference` vào database của bạn	Lưu tiền từ customer vào account trung gian (AgentPay không hỗ trợ)
Kiểm tra bank feed notification trước khi gửi sản phẩm	Tin tưởng client-side callback (luôn xác nhận từ server)
Cấu hình timeout phù hợp (ví dụ: 600 giây = 10 phút)	Đặt timeout quá ngắn (<60 giây) — customer cần thời gian quét QR
Sử dụng mã hoá thông tin bank (env variables)	Hardcode bank account trực tiếp trong code
Retry yêu cầu settlement nếu network bị gián đoạn	Giả sử settlement thành công mà không kiểm tra
Log chi tiết các giao dịch để audit	Xóa logs sau vài ngày

Các tính năng nâng cao

Tạo nhiều yêu cầu thanh toán cùng lúc

from agentpay_vn import PaymentClient
import asyncio

client = PaymentClient(
    bank_account="1234567890",
    bank_code="970418",
    merchant_name="Quán Cà Phê Thắng"
)

async def batch_payments():
    # Tạo 3 yêu cầu thanh toán độc lập
    orders = [
        {"amount": 150000, "order_id": "ORD-001", "description": "2x Cà phê Đen"},
        {"amount": 200000, "order_id": "ORD-002", "description": "1x Bánh Mì Nướng"},
        {"amount": 100000, "order_id": "ORD-003", "description": "1x Nước Cam"},
    ]

    payments = []
    for order in orders:
        payment = client.create_payment_request(
            amount=order["amount"],
            order_id=order["order_id"],
            description=order["description"]
        )
        payments.append(payment)

    # Chờ tất cả thanh toán cùng lúc
    settlements = await asyncio.gather(*[
        client.await_settlement(p.reference, timeout=600) for p in payments
    ])

    for i, settlement in enumerate(settlements):
        if settlement:
            print(f"Order {i+1}: ✓ Thanh toán {settlement.amount} VND")
        else:
            print(f"Order {i+1}: ✗ Chưa thanh toán")

# Chạy
asyncio.run(batch_payments())

Tích hợp retry logic

import asyncio
from agentpay_vn import PaymentClient

async def wait_with_retry(client, reference, max_retries=3, timeout_per_attempt=300):
    """
    Chờ settlement với cơ chế retry.
    Nếu timeout, retry lên đến max_retries lần.
    """
    for attempt in range(1, max_retries + 1):
        print(f"Lần {attempt}/{max_retries}: Chờ xác nhận...")
        settlement = await client.await_settlement(
            reference=reference,
            timeout=timeout_per_attempt
        )

        if settlement:
            print(f"✓ Thanh toán thành công ở lần {attempt}")
            return settlement

        if attempt < max_retries:
            print(f"  Timeout. Thử lại sau 30 giây...")
            await asyncio.sleep(30)

    print(f"✗ Đã retry {max_retries} lần, vẫn chưa thanh toán")
    return None

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

1. AgentPay VN có giữ tiền của tôi không?

Trả lời: Không. AgentPay VN không bao giờ xử lý hoặc giữ tiền. QR code VietQR được tạo ra luôn trỏ thẳng vào tài khoản ngân hàng của bạn. Tiền từ customer chuyển trực tiếp vào ngân hàng của bạn; AgentPay chỉ giúp tạo QR và xác nhận settlement thông qua bank feed.

2. Làm sao để lấy bank feed notification?

Trả lời: AgentPay VN kết nối với API ngân hàng hoặc webhook bank feed (tùy ngân hàng). Nếu bạn dùng Techcombank, Vietcombank, hay ACB, SDK sẽ tự động poll bank feed mỗi vài giây. Không cần cấu hình thêm.

3. Tôi có thể tùy chỉnh thông báo lỗi khi thanh toán thất bại không?

Trả lời: Có. Nếu await_settlement() trả về None (timeout), bạn có toàn quyền xử lý:

settlement = await client.await_settlement(reference, timeout=600)
if not settlement:
    # Gửi thông báo lỗi custom
    await send_message_to_customer(
        "Oops! Chúng tôi chưa nhận được thanh toán. Vui lòng kiểm tra kết nối mạng và thử lại."
    )

4. Liệu SDK này có hoạt động offline không?

Trả lời: Phần "tạo payment request" hoạt động offline (chỉ cần private key). Nhưng phần "chờ settlement" cần kết nối internet để kết nối bank feed. Nếu mất kết nối, hãy retry sau khi online lại.

Tóm tắt nhanh — Bạn cần nhớ

AgentPay VN = Python SDK + MCP server cho AI agent thu tiền VietQR
Cài đặt: pip install agentpay-vn
3 bước: create_payment_request() → gửi link → await_settlement()
Tiền đi đâu: Trực tiếp vào tài khoản ngân hàng của bạn (không giữ tại AgentPay)
Tích hợp AI: Dùng MCP server để agent gọi function thanh toán như tool bình thường
Kịch bản tốt: Bot bán hàng, khóa học online, booking, SaaS
Cẩn trọng: Luôn xác nhận settlement từ bank feed, không tin callback client
Độc lập: Mã nguồn mở (MIT), tự hosting, không phụ thuộc service bên thứ ba

Bước tiếp theo

Sẵn sàng bắt đầu? Dưới đây là những tài nguyên hữu ích:

Cài đặt ngay: bash pip install agentpay-vn
Đọc tài liệu đầy đủ: - 📖 https://agentpay.servicesai.vn/v1/docs - API reference, ví dụ chi tiết, troubleshooting
Repository GitHub: - 🔗 https://github.com/phuocdu/agentpay-vn - Code mẫu, issue tracking, community discussion
Thử nghiệm: - Tạo test payment request với amount nhỏ - Giả lập bank notification để kiểm tra flow - Deploy MCP server trên Claude Desktop
Tích hợp vào agent hiện tại: - Thêm agentpay-mcp vào config MCP - Viết prompt cho agent để gọi payment function - Test end-to-end với khách hàng thực

Chúc bạn thành công trong việc tự động hoá thanh toán AI! Nếu có câu hỏi, tham gia cộng đồng tại GitHub issues hoặc documentation của AgentPay VN.

Bắt đầu →

← Tất cả bài