Chatbot AI bán sản phẩm số mà không giữ tiền: Hướng dẫn AgentPay

2026-07-20 · AgentPay VN

agentpayai agentspython sdkvietqrchatbot thanh toán

Tình huống: Bot bán khoá học nhưng không dám nhận tiền

Bạn vừa xây dựng một chatbot AI để bán khoá học trực tuyến. Khách hàng yêu cầu thanh toán, bot tạo hoá đơn đẹp lắm—nhưng rồi sao? Bạn phải:

Tự mình lấy tiền từ ví điện tử hoặc tài khoản trung gian (Stripe, PayPal, Momo) → rồi chuyển cho khách hàng hoặc giữ riêng
Chịu trách nhiệm pháp lý nếu xảy ra tranh chấp—bot của bạn đang "giữ" tiền?
Phức tạp hóa quy trình khi phải ghi chép, đối soát, rút tiền thủ công

Đó là lý do AgentPay VN tồn tại. Nó cho phép AI agent tạo mã QR VietQR trỏ thẳng vào tài khoản ngân hàng của bạn, khách quét thanh toán, ngân hàng ghi nhận—xong. Bot không bao giờ "chạm" tiền.

Vì sao cách cũ lại nguy hiểm?

Khi bot giữ hộ tiền (thậm chí qua API gateway):

Rủi ro tuân thủ: Bạn có thể cần giấy phép từ Ngân hàng Nhà nước nếu thường xuyên xử lý giao dịch
Phức tạp kế toán: Kiểm toán sẽ tếu khi thấy tiền "lơ lửng" giữa bot và tài khoản
Trải nghiệm chậm: Khách chờ bot xác nhận settlement, rồi chờ bot gửi tiền tới—độ trễ 1-2 ngày
Khó bảo mật: Bạn phải quản lý API key của gateway, tránh bị tấn công SQL injection hay XSS

AgentPay giải quyết tất cả bằng cách: QR code = tài khoản thực, thanh toán = ghi vào sổ cái thực, xác nhận = webhook từ ngân hàng.

AgentPay VN là gì? Cơ chế hoạt động

AgentPay VN là một bộ công cụ mở (MIT license):

Python SDK: Thư viện agentpay-vn giúp bot tạo payment request, sinh QR code VietQR
MCP Server: Adapter cho Claude (hoặc AI agent khác qua Model Context Protocol) để gọi hàm một cách tự nhiên
Bank feed: Kết nối với webhook của ngân hàng để xác nhận khi khách đã thanh toán

Quy trình 3 bước:

create_payment_request() → send checkout_url() → await_settlement()

Bước 1: Bot tạo yêu cầu thanh toán (amount, description, customer email)
Bước 2: Hệ thống sinh QR code VietQR (trỏ vào tài khoản bạn) + link checkout
Bước 3: Webhook từ ngân hàng ghi "tiền đã về" → bot tự động phát hành sản phẩm số (PDF khoá học, API key, vv.)

Tiền không bao giờ qua tay bot—nó đi thẳng từ khách hàng → ngân hàng của bạn.

Cài đặt và khởi động nhanh

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

pip install agentpay-vn

Thế là xong. Không cần secret key từ gateway bên thứ ba, không cần đăng ký thêm tài khoản thanh toán.

Bước 2: Tạo payment request đơn giản

from agentpay_vn import AgentPayClient

# Khởi tạo client (chỉ cần tài khoản VietQR của bạn)
client = AgentPayClient(
    merchant_account="1234567890",  # Số tài khoản VietQR
    merchant_name="Cà phê AI Việt Nam",
    bank_code="MB"  # Mã ngân hàng (MB = MBBank, ACB, etc.)
)

# Tạo payment request cho 1 phần cà phê
payment = client.create_payment_request(
    amount=50000,  # 50,000 VNĐ
    description="Cà phê chuyên biệt AI",
    customer_email="khach@example.com",
    order_id="ORDER_001"
)

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

Giải thích: - merchant_account: Số tài khoản VietQR của bạn tại ngân hàng (không phải API key) - amount: Số tiền khách cần thanh toán - customer_email: Email để bot gửi hoá đơn/xác nhận sau khi thanh toán thành công - Kết quả: Một link QR + URL checkout mà bạn gửi cho khách qua bot

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

import asyncio
from agentpay_vn import AgentPayClient

client = AgentPayClient(
    merchant_account="1234567890",
    merchant_name="Cà phê AI Việt Nam",
    bank_code="MB"
)

async def wait_for_payment(payment_id, timeout=300):
    """
    Chờ tối đa 5 phút để khách thanh toán.
    Khi webhook từ ngân hàng về, settle.status sẽ chuyển thành 'completed'.
    """
    settle = await client.await_settlement(
        payment_id=payment_id,
        timeout_seconds=timeout
    )

    if settle.status == "completed":
        print(f"✅ Thanh toán thành công! Số tiền: {settle.amount} VNĐ")
        print(f"   Từ tài khoản: {settle.payer_account}")
        print(f"   Reference: {settle.reference}")

        # 👇 Tại đây, bot có thể tự động phát hành sản phẩm
        # Ví dụ: gửi email với link download khoá học
        # send_course_download_link(settle.customer_email, course_id="COURSE_001")

        return True
    else:
        print(f"❌ Thanh toán không hoàn tất. Trạng thái: {settle.status}")
        return False

# Sử dụng
payment_id = "PAY_20250124_001"  # Từ bước 2
result = asyncio.run(wait_for_payment(payment_id))

Điểm mạnh: - await_settlement() chỉ trả về khi webhook từ ngân hàng xác nhận = tiền đã thực sự vào tài khoản bạn - Không có xác nhận giả, không có "chờ xác nhận lại" - Timeout tránh bot bị treo vô tận

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

Nếu bạn dùng Claude hay AI agent khác hỗ trợ Model Context Protocol, bạn có thể cho bot tự động gọi hàm payment mà không cần code:

Cấu hình MCP cho Claude

{
  "mcpServers": {
    "agentpay-vn": {
      "command": "agentpay-mcp",
      "args": [
        "--merchant-account",
        "1234567890",
        "--merchant-name",
        "Cà phê AI Việt Nam",
        "--bank-code",
        "MB"
      ],
      "env": {
        "AGENTPAY_WEBHOOK_URL": "https://yourdomain.com/webhook/agentpay"
      }
    }
  }
}

Sau khi setup:

Bạn (user):  "Bán cho tôi 1 khoá học Python nâng cao, giá 299k"

Claude:
  1. Tạo payment request: create_payment_request(amount=299000, description="Python nâng cao")
  2. Trả về link QR + checkout URL
  3. Tự động chờ settlement bằng await_settlement()
  4. Khi tiền đã về: "✅ Thanh toán thành công. Đang gửi khoá học tới email của bạn..."

Bot hoàn toàn tự động, không cần can thiệp từ server bạn.

Ví dụ thực tế: Bot quán cà phê bán online

Giả sử bạn chạy một quán cà phê nhỏ ở Hà Nội, muốn bán cà phê online qua bot Telegram:

Luồng đơn hàng

👤 Khách: "Tôi muốn đặt 2 cà phê đen, 1 cà phê sữa. Tổng: 180k"

🤖 Bot:
   1. Tạo payment request → AgentPay
   2. Gửi QR code + link checkout
   3. "Quý khách vui lòng quét mã QR để thanh toán"

💳 Khách quét QR (không phải QR giả, là QR VietQR thực) → thanh toán 180k

🏦 Ngân hàng của quán: nhận tiền 180k (instant)

🤖 Bot:
   1. Nhận webhook từ ngân hàng: "Settlement confirmed"
   2. Tự động gửi "Đơn hàng của bạn sẽ được giao trong 1 giờ. Mã đơn: #12345"
   3. Cập nhật bàng tính Google Sheets: Thêm 1 hàng "180k, Telegram ID 12345678, 2 đen 1 sữa, settled"

📍 Nhân viên thấy bàng tính → chuẩn bị đồ uống → giao khách

Code bot Telegram tương ứng (pseudocode):

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes
from agentpay_vn import AgentPayClient
import asyncio

client = AgentPayClient(
    merchant_account="1234567890",
    merchant_name="Cà phê AI Hà Nội",
    bank_code="MB"
)

async def order_coffee(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # Giả sử user đã chọn: 2 đen, 1 sữa
    amount = 180000
    order_id = "COFFEE_20250124_001"

    # Bước 1: Tạo payment request
    payment = client.create_payment_request(
        amount=amount,
        description="2 cà phê đen, 1 cà phê sữa",
        customer_email=user_email,
        order_id=order_id
    )

    # Bước 2: Gửi QR code tới khách
    await context.bot.send_message(
        chat_id=update.effective_chat.id,
        text=f"💰 Tổng tiền: {amount:,} VNĐ\n📱 Vui lòng quét QR bên dưới:",
    )
    await context.bot.send_photo(
        chat_id=update.effective_chat.id,
        photo=payment.qr_code_url
    )

    # Bước 3: Chờ settlement (chạy song song không block)
    asyncio.create_task(monitor_payment(payment.id, update.effective_chat.id))

async def monitor_payment(payment_id, chat_id):
    settle = await client.await_settlement(payment_id, timeout_seconds=600)

    if settle.status == "completed":
        await application.bot.send_message(
            chat_id=chat_id,
            text="✅ Thanh toán thành công!\n🚗 Đơn hàng sẽ giao trong 1 giờ. Mã đơn: #12345"
        )
        # Cập nhật Google Sheets, gửi notification tới shop staff, etc.
    else:
        await application.bot.send_message(
            chat_id=chat_id,
            text="⚠️ Thanh toán lỗi hoặc hết thời gian. Vui lòng thử lại."
        )

app = Application.builder().token("YOUR_TELEGRAM_TOKEN").build()
app.add_handler(CommandHandler("order", order_coffee))
app.run_polling()

Nên làm gì, không nên làm gì

Tiêu chí	✅ Nên	❌ Không nên
Giữ lại tiền quá 1-2 ngày	Sử dụng AgentPay, tiền vào tài khoản ngân hàng ngay	Để tiền ở ví điện tử trung gian, cứ lo sợ bị chốt tài khoản
API key thanh toán	Chỉ dùng merchant_account (SỐ TÀI KHOẢN)	Không bao giờ hardcode secret key gateway vào code
Xác nhận thanh toán	Tin tưởng webhook từ ngân hàng + await_settlement()	Tự poll API gateway 100 lần/giây, gây spam
Email khách	Gửi từ server của bạn sau khi settlement confirmed	Gửi qua bot trước khi tiền thực sự về (gây khiếu nại)
Timeout	Để 5-10 phút (tùy timeout quét QR)	Để infinite (bot treo mãi mãi)
Test	Dùng test account VietQR (nếu ngân hàng hỗ trợ)	Chạy test trên tiền thật, vừa phát triển vừa tốn tiền

Các câu hỏi thường gặp

1. Nếu khách không quét QR trong 10 phút thì sao?

Bạn có thể set timeout_seconds=600 (10 phút). Sau đó, await_settlement() sẽ trả về trạng thái timeout. Bot có thể tự động gửi lời nhắc "Thanh toán còn chưa hoàn tất. Vui lòng quét lại mã QR" hoặc xoá đơn hàng khỏi queue.

2. Nếu khách quét QR rồi nhưng sai số tiền thì sao?

QR code VietQR có "nhúng" số tiền vào, khách không thể thay đổi. Nếu cố gắng thanh toán ít hơn, giao dịch bị từ chối. Nếu thanh toán nhiều hơn (vô ý), bạn sẽ nhận được tiền nhiều hơn—bạn có thể hoàn lại khách qua ngân hàng (vài phút xử lý).

3. AgentPay có lưu trữ thông tin khách không?

Không. SDK chỉ tạo QR code từ thông tin bạn cung cấp, rồi bỏ ngoài. Webhook settlement cũng chỉ có: amount, reference, timestamp. Dữ liệu khách (email, phone, tên) hoàn toàn nằm ở hệ thống của bạn.

4. Có phí gì khi dùng AgentPay không?

AgentPay là open-source, miễn phí. Bạn chỉ chịu phí chuyển khoản/rút tiền của ngân hàng nếu có (thường là miễn phí với VietQR).

Tóm tắt nhanh

🎯 AgentPay VN = SDK Python + MCP server để AI agents tạo payment request VietQR mà không giữ tiền
📲 QR code trỏ thẳng vào tài khoản ngân hàng thực của bạn, không qua trung gian
⚡ 3 bước: create_payment_request() → send checkout_url() → await_settlement()
🔐 An toàn: Tiền vào ngân hàng ngay, webhook xác nhận từ ngân hàng, bot tự động phát hành sản phẩm
🛠️ Dễ setup: pip install agentpay-vn, rồi copy code 10 dòng là chạy
💰 Chi phí thấp: Open-source MIT, không phí dịch vụ, chỉ phí ngân hàng (thường miễn)
🤖 Tích hợp AI: MCP server cho Claude, gọi hàm payment như gọi tool thường

Hành động tiếp theo

Cài đặt ngay hôm nay:

pip install agentpay-vn

Xem ví dụ đầy đủ + tài liệu API:

👉 Docs AgentPay VN
👉 GitHub: phuocdu/agentpay-vn

Sắp tới:

Tạo tài khoản VietQR tại ngân hàng (nếu chưa có)
Clone repo example từ GitHub
Cấu hình MCP cho Claude
Deploy bot của bạn

Kết quả: Chatbot bán hàng hoàn toàn tự động, khách thanh toán → tiền vào tài khoản bạn → sản phẩm được gửi tự động. Không cần chạm tiền, không cần giấy phép ngân hàng, không cần lo sợ.

Hãy bắt đầu xây dựng nền tảng bán hàng số an toàn cho bot AI của bạn! 🚀

Bắt đầu →

← Tất cả bài