Thêm thanh toán VietQR vào AI agent Python chỉ trong 10 phút

2026-07-18 · AgentPay VN

aipythonvietqrmcpthanh toán

Bài toán thực tế: AI agent bán hàng không thể nhận tiền

Bạn vừa xây dựng một chatbot bán khoá học trực tuyến, bot tư vấn bất động sản, hoặc hệ thống đặt chỗ nhà hàng chạy trên Claude/OpenAI. Mọi thứ hoạt động tốt—agent trả lời khách hàng thông minh, đưa ra giá cả, thậm chí tạo hóa đơn. Nhưng khi khách hàng nói "tôi muốn mua ngay", agent lại bó tay vì... nó không có khả năng nhận tiền.

Bạn phải tạo workflow riêng, integrare Stripe/Zalopay, xử lý webhook, rồi đợi khoản tiền nằm trong tài khoản trung gian. Mất vài tuần, mã nguồn phức tạp, chi phí phí giao dịch cao.

Có một cách tốt hơn: AgentPay VN—SDK Python mã nguồn mở cho phép AI agent tạo mã QR VietQR, gửi cho khách, và lập tức nhận tiền vào tài khoản ngân hàng của bạn. Chỉ 3 dòng code. Chỉ 10 phút cài đặt.

AgentPay VN là gì? Tại sao bạn cần nó?

AgentPay VN là một SDK Python (MIT License) và MCP server giúp AI agent:

Tạo yêu cầu thanh toán động—mỗi khách hàng một mã QR khác nhau
Không bao giờ giữ tiền—mã QR trỏ trực tiếp tới tài khoản ngân hàng của bạn
Xác nhận thanh toán tự động—dùng bank feed, biết ngay khi khách hàng chuyển tiền
Tích hợp vào Claude/OpenAI dễ dàng—qua MCP (Model Context Protocol)

So với các giải pháp khác:

Tiêu chí	AgentPay VN	Stripe	Zalopay	Chuyển khoản thủ công
Cài đặt	1 lệnh pip	30 phút + auth	1 ngày	N/A
Giữ tiền	Không	Có	Có	Người bán
Phí	0%	2-3%	1-2%	0%
Tích hợp AI	Có (MCP)	Có	Có	Không
Open source	Có	Không	Không	N/A

Cài đặt AgentPay VN: Bước 1 (2 phút)

Mở terminal và chạy:

pip install agentpay-vn

Xong. Không cần API key, không cần đăng ký tài khoản. SDK sẽ dùng thông tin ngân hàng bạn cung cấp sau.

Kiểm tra cài đặt:

python -c "import agentpay; print(agentpay.__version__)"

Luồng thanh toán 3 bước

Truớc khi viết code, hiểu quy trình này:

1. create_payment_request() 
   → Tạo yêu cầu thanh toán (tên khách, số tiền, mô tả)
   → Trả về checkout_url (chứa QR VietQR)

2. send_to_customer()
   → Gửi URL hoặc hiển thị QR cho khách hàng
   → Khách scam QR, chuyển tiền vào tài khoản bạn

3. await_settlement()
   → Chờ bank feed xác nhận
   → Khi tiền về, callback tự động kích hoạt
   → Agent tiếp tục quy trình (gửi hóa đơn, kích hoạt khoá học...)

Ví dụ thực tế: Chatbot bán khoá học online

Hãy tưởng tượng một bot hỗ trợ khách hàng cho nền tảng học lập trình:

Khách hàng: "Tôi muốn mua khoá Python Advanced"

Bot: "Tuyệt! Khoá này giá 499,000 VND. Để thanh toán, vui lòng quét mã QR hoặc bấm vào link dưới đây. Tiền sẽ chuyển trực tiếp tới tài khoản của tôi."

[Hiển thị QR mã VietQR]

Khách hàng: [Quét và chuyển 499,000 VND]

Bot (30 giây sau, khi bank feed xác nhận): "🎉 Tuyệt! Tôi đã nhận tiền của bạn. Tài khoản khoá học của bạn đã được mở. Đây là link tải tài liệu: ..."

Câu chuyện hoàn chỉnh. Không cần bất kỳ tác vụ thủ công nào.

Viết code: Ví dụ cơ bản

Tạo file payment_bot.py:

from agentpay import AgentPayClient, PaymentRequest
import asyncio

# Khởi tạo client (thông tin ngân hàng đọc từ biến môi trường)
client = AgentPayClient()

async def sell_course():
    # Bước 1: Tạo yêu cầu thanh toán
    request = PaymentRequest(
        customer_name="Nguyễn Văn A",
        amount=499000,  # VND
        description="Khoá Python Advanced",
        order_id="course_001_20240101"  # ID duy nhất
    )

    response = await client.create_payment_request(request)
    checkout_url = response.checkout_url
    print(f"Gửi link tới khách: {checkout_url}")

    # Bước 2: Chờ thanh toán (timeout 15 phút)
    settlement = await client.await_settlement(
        order_id="course_001_20240101",
        timeout_seconds=900
    )

    if settlement.status == "confirmed":
        print(f"✅ Nhận {settlement.amount} VND")
        # Kích hoạt khoá học cho khách hàng
        await activate_course("Nguyễn Văn A")
    else:
        print("❌ Thanh toán thất bại hoặc hết thời gian")

async def activate_course(customer_name: str):
    print(f"Gửi link khoá học tới {customer_name}...")
    # Ghi vào database, gửi email, v.v.

if __name__ == "__main__":
    asyncio.run(sell_course())

Giải thích từng dòng:

AgentPayClient(): Khởi tạo client. Nó tự động tìm tài khoản ngân hàng từ .env (hoặc biến môi trường AGENTPAY_*)
PaymentRequest(): Định nghĩa thanh toán—ai, bao nhiêu tiền, mục đích là gì
create_payment_request(): Gọi API VietQR, nhận URL checkout với mã QR được nhúng
await_settlement(): Hàm async chờ bank feed. Khi tiền tới, nó trả về kết quả xác nhận
activate_course(): Logic sau thanh toán—bạn viết phần này

Tích hợp vào Claude với MCP Server

Nếu bạn muốn Claude có thể gọi trực tiếp hàm thanh toán, cài MCP server:

pip install agentpay-mcp
agentpay-mcp  # Chạy server (mặc định port 3000)

Rồi cấu hình Claude (file ~/.claude/config.json):

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "args": [],
      "env": {
        "AGENTPAY_BANK_ACCOUNT": "1234567890",
        "AGENTPAY_BANK_NAME": "VietcomBank",
        "AGENTPAY_ACCOUNT_NAME": "Cua Hang ABC"
      }
    }
  }
}

Bây giờ trong Claude:

User: "Tôi muốn bán một product giá 299,000 VND cho Trần Thị B"

Claude (dùng MCP): "Tôi sẽ tạo yêu cầu thanh toán ngay..."
[Gọi agentpay:create_payment_request với thông tin trên]

Claude: "Vừa tạo mã QR. Đây là link: https://vietqr.io/... Khách hàng quét để thanh toán."
[Sau khi khách quét, Claude đợi via await_settlement]

Claude: "Tiền đã về tài khoản! Hóa đơn được gửi."

Ví dụ nâng cao: Bot quán cà phê (in-store + online)

Quán cà phê muốn có chatbot hỗ trợ: - Khách đặt qua Messenger: "2 cà phê + 1 croissant" - Bot tính tiền (120,000 VND) - Gửi QR thanh toán - Khi tiền về, in bill ở quán

from agentpay import AgentPayClient, PaymentRequest
from datetime import datetime
import json

client = AgentPayClient()

async def coffee_order_flow(customer_id: str, items: list, total: int):
    """
    items = ["cà phê đen", "cà phê đen", "croissant"]
    total = 120000
    """

    # Tạo đơn hàng
    order_id = f"cafe_{customer_id}_{datetime.now().strftime('%Y%m%d%H%M%S')}"
    order_data = {
        "items": items,
        "total": total,
        "timestamp": datetime.now().isoformat()
    }

    # Lưu vào Redis/database
    await save_order(order_id, order_data)

    # Tạo QR thanh toán
    payment = PaymentRequest(
        customer_name=f"KH_{customer_id}",
        amount=total,
        description=f"{len(items)} sản phẩm: {', '.join(items)}",
        order_id=order_id
    )

    result = await client.create_payment_request(payment)
    qr_url = result.checkout_url

    # Gửi tin nhắn cho khách
    await send_messenger(customer_id, f"""Đơn hàng của bạn: {total:,} VND
    Quét mã QR để thanh toán: {qr_url}
    """)

    # Chờ thanh toán
    settlement = await client.await_settlement(order_id, timeout_seconds=600)

    if settlement.status == "confirmed":
        # In bill ở quán
        await print_receipt(order_id, items, total)
        # Thông báo khách
        await send_messenger(customer_id, "✅ Thanh toán thành công! Đơn hàng đang chuẩn bị.")

    return settlement

async def save_order(order_id: str, data: dict):
    # Lưu vào DB
    pass

async def send_messenger(customer_id: str, message: str):
    # Gửi via Messenger API
    pass

async def print_receipt(order_id: str, items: list, total: int):
    # Gửi lệnh in đến máy POS
    print(f"[PRINT] Đơn {order_id}: {items} = {total} VND")

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

Nên: - ✅ Tạo một order_id duy nhất cho mỗi yêu cầu thanh toán - ✅ Lưu order_id vào database để theo dõi - ✅ Dùng timeout_seconds hợp lý (5-15 phút tùy loại hàng) - ✅ Xử lý lỗi mạng trong await_settlement—nếu timeout, gửi reminder cho khách - ✅ Test với số tiền nhỏ trước (1,000-5,000 VND)

Không nên: - ❌ Tái sử dụng order_id cho khách hàng khác - ❌ Bỏ qua bước await_settlement—luôn chờ xác nhận từ bank feed - ❌ Giả sử thanh toán thành công ngay—async chờ, không polling liên tục - ❌ Lưu thông tin ngân hàng trong code—dùng biến môi trường - ❌ Quên xử lý edge case (khách chuyển sai số tiền, transfer lại sau)

Cấu hình biến môi trường

Tạo file .env trong thư mục project:

# .env
AGENTPAY_BANK_ACCOUNT=1234567890
AGENTPAY_BANK_NAME=VietcomBank  # hoặc VPBank, TPBank, v.v.
AGENTPAY_ACCOUNT_NAME=Cua Hang ABC
AGENTPAY_API_ENDPOINT=https://agentpay.servicesai.vn/v1  # (tùy chọn)

Trong code:

import os
from dotenv import load_dotenv

load_dotenv()

bank_account = os.getenv("AGENTPAY_BANK_ACCOUNT")
bank_name = os.getenv("AGENTPAY_BANK_NAME")
# Không cần truyền—client tự động đọc

Thường gặp: FAQ

Q: Nếu khách chuyển sai số tiền (ví dụ 498,000 thay vì 499,000), sao?

A: settlement sẽ báo lỗi (số tiền không khớp). Bạn có thể: 1. Gửi thông báo cho khách: "Bạn chuyển thiếu 1,000 VND, vui lòng chuyển thêm" 2. Tạo yêu cầu mới với số tiền còn thiếu 3. Hoặc chấp nhận và giảm giá cho khách (tuỳ chính sách)

AgentPay VN không tự động xử lý trường hợp này—bạn kiểm soát logic.

Q: Có thể tạo multiple payment requests cùng lúc cho cùng một khách?

A: Có, miễn là mỗi yêu cầu có order_id khác nhau. Ví dụ khách mua 2 sản phẩm riêng: - order_id: product_A_20240101_1 → 199,000 VND - order_id: product_B_20240101_2 → 299,000 VND

Khách chuyển tiền cho cả 2, bot nhận.

Q: AgentPay VN có phụ thuộc vào Stripe/Zalopay không?

A: Không. Nó dùng VietQR và bank feed của ngân hàng Việt Nam. Tiền trực tiếp vào tài khoản bạn, không qua trung gian.

Q: Tôi dùng OpenAI API (gpt-4-turbo) thay vì Claude, có được không?

A: Có! AgentPay VN là SDK Python tầm thấp, không phụ thuộc vào Claude. Bạn có thể: - Dùng create_payment_request() trong prompt engineering - Hoặc gọi trực tiếp trong code khi OpenAI trả về action cần thiết - MCP server chủ yếu cho Claude; với OpenAI dùng Function Calling thay thế

Tóm tắt nhanh

Là gì: SDK Python + MCP server cho AI agent nhận thanh toán VietQR
Cài: pip install agentpay-vn (1 lệnh, 30 giây)
Không giữ tiền: Mã QR trỏ tới tài khoản ngân hàng bạn, hết.
3 bước chính: 1. create_payment_request() → tạo QR 2. Gửi URL/QR cho khách 3. await_settlement() → chờ xác nhận tiền về
Trường hợp sử dụng: Bot bán khoá học, nhà hàng, shop online, tư vấn bất động sản, v.v.
Giảm độ phức tạp: Thay vì 3-4 tuần integrare Stripe, bây giờ chỉ 10 phút
Mã nguồn mở: MIT License, tự do tùy chỉnh

Bước tiếp theo

Cài đặt ngay: bash pip install agentpay-vn
Xem tài liệu chi tiết: https://agentpay.servicesai.vn/v1/docs
Clone repo để xem ví dụ: bash git clone https://github.com/phuocdu/agentpay-vn cd examples/
Chạy bot đầu tiên của bạn (dùng mẫu cơ bản ở trên)
Tham gia cộng đồng: Issues/Discussions trên GitHub để hỏi đáp

Tháng sau, bạn sẽ tưởng đẫy đà vì bot bán hàng tự động của mình. Hãy bắt đầu ngay hôm nay! 🚀

Bắt đầu →

← Tất cả bài