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

2026-09-14 · AgentPay VN

aipythonvietqragentpaymcp

Nỗi đau của startup tech Việt khi tích hợp thanh toán

Bạn vừa xây dựng một chatbot AI bán khoá học online, hoặc một agent tự động nhận đơn đặt hàng. Mọi thứ hoạt động tuyệt vời... cho đến khi cần thu tiền. Stripe yêu cầu công ty con ở Mỹ. Zalopay, MoMo có phí giao dịch cao và không hỗ trợ API dễ dùng cho agent. Bạn loanh quanh tìm giải pháp nhưng hầu hết đều phức tạp, đắt tiền, hoặc không phù hợp với workflow AI.

Có một cách tốt hơn: AgentPay VN – một SDK Python open-source (MIT) cho phép AI agent của bạn thu tiền trực tiếp vào tài khoản ngân hàng qua VietQR, mà không cần trung gian giữ tiền.

Tại sao AgentPay VN là giải pháp "made for Vietnam"?

AgentPay VN giải quyết ba bài toán cứng nhất:

1. Không cần tài khoản quốc tế

VietQR là tiêu chuẩn quốc gia, tất cả ngân hàng Việt Nam đều hỗ trợ. Bạn chỉ cần một tài khoản ngân hàng nội địa.

2. SDK tối thiểu, tập trung vào business logic

Thay vì code 200+ dòng để xử lý webhook, retry, reconciliation, AgentPay VN gói gọn trong ba bước: - create_payment_request() – tạo yêu cầu thanh toán - send_checkout_url() – gửi link QR tới khách - await_settlement() – chờ ngân hàng xác nhận tiền về

3. Money never touches AgentPay

QR code trỏ thẳng vào tài khoản merchant của bạn. Ngân hàng gửi bank feed để xác nhận. Bạn kiểm soát 100% dòng tiền.

Cài đặt AgentPay VN trong 2 phút

Bước 1: Cài SDK Python

pip install agentpay-vn

Bước 2: Cấu hình MCP Server (cho Claude/LLM)

Nếu bạn dùng Claude hoặc LLM khác qua MCP, thêm vào claude_desktop_config.json (hoặc tương đương):

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"]
    }
  }
}

Hoặc cài trực tiếp:

pip install agentpay-mcp

Bước 3: Set biến môi trường (tùy chọn)

export AGENTPAY_MERCHANT_ID="your_merchant_vietqr_id"
export AGENTPAY_BANK_ACCOUNT="your_bank_account_number"

Hướng dẫn từng bước: Tạo yêu cầu thanh toán

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

Hãy tưởng tượng một agent AI giới thiệu khoá học Python cho khách, sau đó tự động xin thanh toán.

from agentpay_vn import PaymentRequest, SettlementWatcher
import asyncio
from datetime import datetime, timedelta

# Bước 1: Khởi tạo yêu cầu thanh toán
payment = PaymentRequest(
    merchant_id="DEMO_MERCHANT",  # ID của bạn từ VietQR
    amount_vnd=299000,              # Giá khoá học: 299k VND
    description="Khoá học Python cơ bản - Tháng 1/2025",
    order_id=f"order_{int(datetime.now().timestamp())}",
    customer_name="Nguyễn Văn A",
    customer_phone="0901234567"
)

# Bước 2: Tạo link checkout
checkout_url = payment.generate_checkout_url()
print(f"📱 Gửi link QR cho khách: {checkout_url}")

# Bước 3: Chờ xác nhận thanh toán từ ngân hàng
watcher = SettlementWatcher(
    order_id=payment.order_id,
    timeout_seconds=3600  # Chờ tối đa 1 giờ
)

try:
    settlement_info = await watcher.await_settlement()
    print(f"✅ Thanh toán thành công!")
    print(f"   Số tiền: {settlement_info['amount']} VND")
    print(f"   Thời gian: {settlement_info['timestamp']}")
    print(f"   Mã giao dịch: {settlement_info['transaction_id']}")
except TimeoutError:
    print("⏱️ Khách chưa thanh toán trong 1 giờ, hủy đơn.")

Giải thích từng dòng: - PaymentRequest() – Tạo đối tượng yêu cầu thanh toán với thông tin cơ bản. - merchant_id – ID VietQR của bạn (lấy từ ngân hàng). - amount_vnd – Số tiền cần thu (ở đây 299,000 đồng). - description – Mô tả sản phẩm hiển thị trên QR code. - generate_checkout_url() – Trả về URL chứa QR code động. - SettlementWatcher – Theo dõi xác nhận từ bank feed ngân hàng. - await_settlement() – Async function chờ tiền về (không block thread).

Ví dụ 2: Tích hợp vào Discord Bot

import discord
from agentpay_vn import PaymentRequest, SettlementWatcher
import asyncio

class PaymentCog(discord.Cog):
    def __init__(self, bot):
        self.bot = bot

    @discord.slash_command(name="mua_premium")
    async def buy_premium(self, ctx):
        # Tạo yêu cầu thanh toán
        payment = PaymentRequest(
            merchant_id="YOUR_MERCHANT_ID",
            amount_vnd=99000,
            description="Discord Premium Role (1 tháng)",
            order_id=f"discord_{ctx.author.id}_{int(datetime.now().timestamp())}",
            customer_name=ctx.author.name,
            customer_phone="unknown"  # Không bắt buộc
        )

        url = payment.generate_checkout_url()

        # Gửi embed với QR code link
        embed = discord.Embed(
            title="💳 Thanh toán Premium",
            description=f"Nhấn nút dưới để thanh toán 99,000 VND",
            color=discord.Color.blue()
        )
        embed.add_field(name="Mã đơn", value=payment.order_id, inline=False)

        button = discord.ui.Button(
            label="Thanh toán VietQR",
            url=url,
            style=discord.ButtonStyle.link
        )
        view = discord.ui.View()
        view.add_item(button)

        await ctx.respond(embed=embed, view=view)

        # Chờ xác nhận thanh toán
        watcher = SettlementWatcher(order_id=payment.order_id, timeout_seconds=600)

        try:
            result = await watcher.await_settlement()
            # Cấp quyền Premium cho user
            role = discord.utils.get(ctx.guild.roles, name="Premium")
            await ctx.author.add_roles(role)
            await ctx.followup.send(f"✅ Bạn đã được cấp quyền Premium!", ephemeral=True)
        except TimeoutError:
            await ctx.followup.send(f"⏱️ Hết thời gian thanh toán. Vui lòng thử lại.", ephemeral=True)

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

Quán cà phê nhỏ muốn có hệ thống thanh toán AI tự động mà không cần máy POS đắt tiền:

Khách gọi chatbot (WhatsApp hoặc web): "Tôi muốn 2 cà phê đen + 1 bánh mì"
Agent tính toán: 25k + 25k + 15k = 65,000 VND
Bot gửi link QR: "Vui lòng quét mã này để thanh toán"
Khách quét bằng ứng dụng ngân hàng (VPBank, Techcombank, Agribank, v.v.)
Khi ngân hàng xác nhận, bot tự động in đơn cho quầy
Nhân viên giao sản phẩm

Lợi ích: - Không phải cấu hình POS phức tạp - Phí giao dịch thấp hơn MoMo/ZaloPay (~0.5% vs 2-3%) - Tiền về ngay tức thì (không chờ settlement hàng ngày) - Kiểm soát hoàn toàn dòng tiền

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

Tiêu chí	AgentPay VN	Stripe	MoMo	ZaloPay	PayPal
Hỗ trợ Việt Nam	✅ VietQR	❌ Cần công ty con	✅	✅	❌ Phí cao
Phí giao dịch	~0.5%	2.9% + 0.3$	2%	1-2%	3.49% + fix
Yêu cầu KYC	Thấp	Cao	Trung bình	Cao	Rất cao
API cho Agent	✅ MCP	Phức tạp	API cơ bản	API cơ bản	Không
Open-source	✅ MIT	❌	❌	❌	❌
Tiền ở trung gian	❌	✅ (Stripe)	✅ (MoMo)	✅ (ZaloPay)	✅ (PayPal)
Self-hosted	✅	❌	❌	❌	❌

Nên và Không Nên khi dùng AgentPay VN

✅ Nên

Dùng cho startup/SME Việt Nam muốn scale nhanh mà không phụ thuộc nước ngoài
Xây dựng AI agent cần gọi thanh toán trong flow logic
Muốn kiểm soát 100% dòng tiền (tiền về trực tiếp tài khoản)
Tích hợp với bot Discord, Telegram, WhatsApp
Sử dụng MCP server cho Claude hoặc LLM khác
Các dự án yêu cầu open-source và customizable

❌ Không Nên

Nếu bạn chỉ cần thanh toán một lần/tháng (overhead không đáng)
Bán hàng quốc tế (hạn chế VietQR, chỉ hỗ trợ Việt Nam)
Cần máy POS vật lý (AgentPay là digital-first)
Doanh số < 10 triệu VND/tháng (không đạt quy mô tối thiểu)

Cấu hình MCP cho Claude

Nếu bạn muốn Claude (qua Claude Desktop) có thể gọi hàm AgentPay trực tiếp:

{
  "mcpServers": {
    "agentpay-vn": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "AGENTPAY_MERCHANT_ID": "YOUR_MERCHANT_ID",
        "AGENTPAY_BANK_ACCOUNT": "1234567890",
        "AGENTPAY_BANK_CODE": "970422"
      }
    }
  }
}

Sau đó, Claude có thể tự gọi lệnh:

User: "Tạo yêu cầu thanh toán 500k cho Tuấn"

Claude → gọi agentpay.create_payment_request(
  amount=500000,
  customer_name="Tuấn"
)

Claude response: "Đã tạo link QR. Gửi cho Tuấn: https://...."

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

1. Làm sao lấy Merchant ID VietQR?

Trả lời: Bạn cần liên hệ với ngân hàng (VPBank, Techcombank, Agribank, v.v.) và đăng ký VietQR Business. Thường Free hoặc phí quản lý 0-50k/tháng. Merchant ID sẽ được cấp sau 1-2 ngày làm việc.

2. Nếu khách không thanh toán trong vòng 1 giờ, sao?

Trả lời: Sử dụng tham số timeout_seconds trong SettlementWatcher. Khi hết thời gian, exception TimeoutError sẽ raise. Lúc này bạn có thể gửi reminder hoặc huỷ đơn.

3. AgentPay giữ tiền hay không?

Trả lời: KHÔNG. QR code trỏ thẳng vào tài khoản merchant (tài khoản ngân hàng của bạn). AgentPay chỉ là SDK để tạo/quản lý request. Tiền về account bạn sau khi khách thanh toán (thường < 30 phút).

4. Có hỗ trợ refund hay hoàn tiền không?

Trả lời: Hiện tại AgentPay V1 chưa tích hợp refund tự động. Bạn cần liên hệ ngân hàng hoặc chuyển tiền lại thủ công. Dự kiến V2 sẽ hỗ trợ.

5. Tôi muốn tích hợp với website Flask/FastAPI của tôi, làm sao?

Trả lời: Dùng webhook bank feed hoặc polling mechanism trong AgentPay. Ví dụ:

from flask import Flask, jsonify
from agentpay_vn import SettlementWatcher

app = Flask(__name__)

@app.route('/check_payment/<order_id>')
def check_payment(order_id):
    watcher = SettlementWatcher(order_id=order_id)
    try:
        result = watcher.await_settlement(timeout_seconds=5)  # Poll 5s
        return jsonify({"status": "paid", "data": result})
    except TimeoutError:
        return jsonify({"status": "pending"})

Tóm tắt nhanh

AgentPay VN = SDK Python + MCP server cho AI agent thu tiền VietQR
Cài đặt: pip install agentpay-vn (1 dòng lệnh)
3 bước cơ bản: create_payment_request() → generate_checkout_url() → await_settlement()
Tiền không qua trung gian – VietQR trỏ thẳng tài khoản ngân hàng của bạn
Open-source MIT – Tự host, customize, không phí hidden
Phù hợp cho: Bot Discord, Telegram, chatbot AI, e-commerce nhỏ, quán ăn, khoá học online
Ưu điểm: Phí thấp (~0.5%), chỉ cần 1 account ngân hàng Việt Nam, API đơn giản cho agent
Hạn chế: Chỉ hoạt động Việt Nam, cần bank account địa phương

Các bước tiếp theo

Cài đặt ngay: pip install agentpay-vn
Đọc tài liệu chi tiết: https://agentpay.servicesai.vn/v1/docs
Xem source code: https://github.com/phuocdu/agentpay-vn
Đăng ký Merchant VietQR với ngân hàng của bạn
Viết agent đầu tiên sử dụng template ở trên
Deploy và test với khách hàng thực

Nếu bạn là founder startup tech, developer tự do, hoặc chủ doanh nghiệp nhỏ ở Việt Nam – AgentPay VN là giải pháp thanh toán AI-native mà bạn cần. Không phức tạp, không phí cao, không trung gian. Chỉ là mã, QR, và tài khoản ngân hàng của bạn.

Hãy bắt đầu ngay hôm nay! 🚀

Bắt đầu →

← Tất cả bài