Thu tiền VietQR cho AI Agent: Hướng dẫn AgentPay VN

2026-08-16 · AgentPay VN

agentpayvietqraipythonmcp

Bài toán thực tế: Tại sao bot AI của bạn không thể kiếm tiền?

Hình dung bạn vừa xây dựng một chatbot bán khóa học tiếng Anh trên Telegram. Bot vừa thông minh (dùng Claude API), vừa kiên nhẫn giải đáp câu hỏi học viên—nhưng khi khách muốn thanh toán 299.000 đ, bạn lại phải... bảo họ chuyển tiền vào tài khoản ngân hàng. Cơ hội mất đi. Hoặc bạn đã thử dùng Stripe, nhưng phí quốc tế lên đến 3.6% + 10.000 đ/giao dịch, và Stripe không support toàn bộ ngân hàng Việt.

Đó chính là lỗ hổng mà AgentPay VN lấp đầy: một Python SDK open-source cho phép AI agent của bạn tự động thu tiền qua VietQR—trực tiếp vào tài khoản ngân hàng thực của bạn—mà không bao giờ nắm giữ một đồng nào.

AgentPay VN là gì? Tại sao nó thay đổi cuộc chơi?

AgentPay VN là một MCP server + Python SDK mã nguồn mở (giấy phép MIT) được thiết kế riêng cho các AI agent cần xử lý thanh toán Việt Nam. Thay vì dùng Stripe (phí cao, thủ tục phức tạp) hoặc tạo form thanh toán thủ công (mất thời gian), bạn có thể:

Tạo request thanh toán từ code AI agent của bạn
Gửi link checkout đến khách (hoặc QR code)
Chờ xác nhận từ bank feed: khi khách chuyển tiền, hệ thống tự động xác nhận settlement

Không cần giữ tiền, không cần tích hợp gateway phức tạp, không cần chờ phê duyệt 2-3 tuần. Mọi thứ chảy vào tài khoản thật của bạn trong vòng vài phút.

So sánh: AgentPay VN vs các giải pháp cũ

Tiêu chí	AgentPay VN	Stripe	Chuyển khoản thủ công
Phí	Miễn phí (open-source)	3.6% + 10k/giao dịch	0%
Tốc độ tích hợp	5 phút	2-3 tuần + review	N/A
Tự động xác nhận	✓ (bank feed)	✓	✗
Giữ tiền	✗	✓ (trước khi rút)	✗
Hỗ trợ VietQR	✓ (tất cả ngân hàng)	✗	✓
Code complexity	Cực thấp (3 dòng)	Trung bình	Không có

Cài đặt & Setup nhanh

Bước 1: Cài Python SDK

Cứ chạy một dòng lệnh:

pip install agentpay-vn

SDK này chứa: - PaymentClient: class chính để tạo payment request - PaymentRequest & PaymentResponse: data models - Các hàm utility để xác nhận settlement qua bank feed

Bước 2: Setup MCP Server (cho Claude)

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

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "args": [
        "--api-key",
        "your_bank_api_key_here",
        "--merchant-id",
        "your_merchant_id"
      ],
      "env": {
        "AGENTPAY_WEBHOOK_URL": "https://yourdomain.com/webhook"
      }
    }
  }
}

MCP server này cho phép Claude gọi AgentPay như một tool tích hợp, chứ không cần viết code từ đầu.

Flow cơ bản: 3 bước tự động hóa thanh toán

Khối lệnh 1: Tạo Payment Request

from agentpay_vn import PaymentClient, PaymentRequest

# Khởi tạo client với API key từ ngân hàng của bạn
client = PaymentClient(api_key="sk_live_xxxxxxxxxx")

# Tạo request thanh toán
payment_req = PaymentRequest(
    merchant_id="MERCHANT_123",           # ID shop của bạn
    amount=299000,                         # Giá khóa học (đơn vị: đồng)
    description="Khóa học English Pro 3 tháng",  # Mô tả
    customer_name="Nguyễn Văn A",         # Tên khách
    customer_phone="0901234567",          # SĐT khách
    order_id="ORD_20250115_001",          # Mã đơn hàng duy nhất
    callback_url="https://yourdomain.com/payment-callback"  # Webhook xác nhận
)

# Gửi request đến hệ thống
response = client.create_payment_request(payment_req)

print(f"QR Code URL: {response.qr_code_url}")
print(f"Checkout URL: {response.checkout_url}")
print(f"Payment ID: {response.payment_id}")

Giải thích: - api_key: Lấy từ cổng quản lý ngân hàng (vd: VCB, Vietcombank) - amount: Số tiền tính bằng đồng Việt Nam (không cần quy đổi) - callback_url: Webhook mà hệ thống sẽ gọi khi thanh toán hoàn tất. Đây là cách bạn biết khách đã chuyển tiền.

Khối lệnh 2: Gửi checkout_url cho khách

# Ví dụ: Gửi link thanh toán qua Telegram bot
import asyncio
from telegram import Bot

async def send_payment_link(user_id, checkout_url):
    bot = Bot(token="YOUR_TELEGRAM_BOT_TOKEN")
    await bot.send_message(
        chat_id=user_id,
        text=f"""✨ Cảm ơn bạn đã chọn khóa học!

Nhấn nút dưới để thanh toán an toàn:
        """,
        reply_markup={
            "inline_keyboard": [[
                {
                    "text": "💳 Thanh toán ngay",
                    "url": checkout_url
                }
            ]]
        }
    )

# Gọi async function
asyncio.run(send_payment_link(user_id=123456789, checkout_url=response.checkout_url))

Khách nhấn nút → Được dẫn đến trang thanh toán → Quét QR VietQR bằng app ngân hàng → Chuyển tiền → Xong!

Khối lệnh 3: Xác nhận settlement (webhook handler)

from flask import Flask, request
import hmac
import hashlib

app = Flask(__name__)

@app.route("/payment-callback", methods=["POST"])
def payment_callback():
    """
    Endpoint này được gọi bởi AgentPay server khi thanh toán hoàn tất.
    """
    # Lấy dữ liệu từ request
    data = request.json
    signature = request.headers.get("X-Signature")

    # Xác thực chữ ký (đảm bảo yêu cầu từ AgentPay server thực sự)
    secret = "sk_live_xxxxxxxxxx"  # API key của bạn
    expected_sig = hmac.new(
        secret.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if signature != expected_sig:
        return {"status": "error", "message": "Invalid signature"}, 403

    # Xử lý khi thanh toán thành công
    if data["status"] == "settled":
        payment_id = data["payment_id"]
        amount = data["amount"]
        order_id = data["order_id"]

        # Cập nhật database: đánh dấu đơn hàng này là đã thanh toán
        # → Cấp quyền truy cập khóa học cho user
        print(f"✓ Thanh toán {order_id} thành công: {amount} VNĐ")
        grant_course_access(order_id)  # Hàm của bạn

        return {"status": "ok", "message": "Payment processed"}, 200

    return {"status": "ok"}, 200

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Điểm mấu chốt: - Mỗi webhook nhận được = một thanh toán đã xác nhận từ ngân hàng - Không cần polling hay chờ đợi: hệ thống tự động báo khi tiền vào - Chữ ký HMAC bảo vệ chống giả mạo

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

Hãy tưởng tượng bạn chạy một cửa hàng khóa học trực tuyến:

Khách → Telegram bot:

Khách: "Mình muốn mua khóa học IELTS"
Bot: "OK, khóa IELTS 3 tháng giá 899.000 VNĐ. Bạn tên gì?"
Khách: "Tôi là Minh"
Bot: "Cảm ơn Minh! Nhấn nút dưới để thanh toán" [💳 Thanh toán]

Phía backend (code bạn):

from agentpay_vn import PaymentClient, PaymentRequest
from telegram.ext import Application, MessageHandler, filters, ContextTypes

PAYMENT_CLIENT = PaymentClient(api_key="sk_live_xxx")

async def handle_course_purchase(update, context):
    user_id = update.effective_user.id
    user_name = update.effective_user.first_name or "Khách"

    # Bước 1: Tạo payment request
    payment_req = PaymentRequest(
        merchant_id="SHOP_IELTS",
        amount=899000,  # Giá khóa IELTS
        description="Khóa IELTS 3 tháng",
        customer_name=user_name,
        customer_phone=update.message.text or "0",
        order_id=f"TG_{user_id}_{int(time.time())}",
        callback_url="https://yourdomain.com/webhook"
    )

    response = PAYMENT_CLIENT.create_payment_request(payment_req)

    # Bước 2: Gửi link checkout
    await update.message.reply_text(
        f"💳 Vui lòng thanh toán: {response.checkout_url}",
        reply_markup=InlineKeyboardMarkup([[
            InlineKeyboardButton("Thanh toán", url=response.checkout_url)
        ]])
    )

# Webhook xác nhận thanh toán → Cấp quyền truy cập khóa học
@app.route("/webhook", methods=["POST"])
def webhook():
    data = request.json
    if data["status"] == "settled":
        order_id = data["order_id"]
        # Trích user_id từ order_id (TG_123456789_...)
        user_id = int(order_id.split("_")[1])
        # Gửi tin nhắn cho khách: "Khóa học đã được mở, hãy vào learn.yourdomain.com"
        send_telegram_message(user_id, "✓ Thanh toán thành công! Link khóa học: ...")
    return {"status": "ok"}, 200

Kết quả: - Khách thanh toán ngay trong app Telegram/web - Tiền vào tài khoản ngân hàng thực của bạn trong vài phút - Bot tự động cấp quyền truy cập khóa học - Không cần bất kỳ trung gian nào

Nâng cao: Tích hợp với Claude AI Agent

Nếu bạn dùng Claude API + MCP, bạn có thể yêu cầu Claude tự động xử lý thanh toán mà không cần code từng bước:

Prompt bạn gửi cho Claude:

Bạn là trợ lý bán hàng.
Khi khách muốn mua gì, hãy:
1. Xác nhận tên, SĐT
2. Dùng tool "create_payment" của AgentPay để tạo payment request
3. Gửi checkout URL cho khách

Từ giờ, tất cả thanh toán được xử lý tự động.

Claude sẽ tự động gọi:

{
  "tool": "agentpay_create_payment",
  "params": {
    "amount": 299000,
    "description": "Sản phẩm gì đó",
    "customer_name": "Tên khách",
    "customer_phone": "SĐT khách"
  }
}

Và Claude sẽ tự động gửi link checkout cho khách, mà bạn không phải viết một dòng code cho phần này.

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

1. Tiền sẽ vào tài khoản của tôi bao lâu?

Thường là 3-5 phút sau khi khách chuyển tiền từ app ngân hàng. AgentPay không giữ tiền—nó chỉ xác nhận từ bank feed của bạn khi tiền đã vào.

2. Tôi có cần tài khoản merchant riêng không?

Không. Bạn chỉ cần một tài khoản ngân hàng thông thường (VCB, ACB, Techcombank, v.v.) có bật VietQR. Phần lớn ngân hàng Việt hỗ trợ.

3. AgentPay có thể bị hack để lấy tiền của tôi không?

Không. AgentPay không bao giờ nắm giữ tiền hoặc chi tiết ngân hàng của bạn. Nó chỉ: - Tạo QR code trỏ đến tài khoản ngân hàng thực của bạn - Xác nhận xem tiền đã vào chưa (thông qua bank feed)

Tiền luôn ở trong tài khoản ngân hàng thực của bạn.

4. Có phí gì không?

SDK là open-source (miễn phí). Bạn chỉ cần thanh toán phí ngân hàng bình thường nếu có (thường là 0% cho VietQR).

Nên / Không nên

✅ Nên dùng AgentPay VN khi:

Bạn cần AI agent tự động xử lý thanh toán
Bạn muốn tránh phí Stripe cao (3.6%+)
Bạn cần triển khai nhanh (không chờ phê duyệt)
Bạn chỉ nhận thanh toán Việt Nam
Bạn muốn full control trên tiền (không trung gian)

❌ Không nên khi:

Bạn cần thanh toán quốc tế (AgentPay chỉ support VietQR Việt Nam)
Bạn muốn webhook tự động từ sẵn (agentpay-mcp giải quyết điều này)
Bạn không muốn tự host webhook endpoint

Tóm tắt nhanh

AgentPay VN = Python SDK open-source giúp AI agent thu tiền VietQR
Không giữ tiền → tiền vào tài khoản ngân hàng thực của bạn
3 bước: create_payment_request() → gửi checkout_url → await_settlement() qua webhook
Setup nhanh: pip install agentpay-vn + cấu hình MCP (5 phút)
Phí thấp: miễn phí SDK + phí ngân hàng bình thường (0% VietQR)
Ví dụ thực tế: Bot Telegram bán khóa học, quán cà phê, shop online
Tích hợp AI: Claude + MCP server = bot tự động xử lý thanh toán mà không code

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

Cài SDK: bash pip install agentpay-vn
Xem ví dụ đầy đủ: 📖 Tài liệu chính thức
Lấy source code & đóng góp: 🔗 GitHub: phuocdu/agentpay-vn
Kiểm tra MCP server: Cài agentpay-mcp nếu bạn dùng Claude Desktop: pip install agentpay-mcp

Bây giờ bot AI của bạn không chỉ thông minh, mà còn có thể kiếm tiền mà không cần bạn can thiệp. Chúc bạn thành công! 🚀

Bắt đầu →

← Tất cả bài