Tự động thu tiền VietQR cho AI agent - Thay thế Stripe Việt Nam

2026-10-06 · AgentPay VN

ai-agentsvietqrpython-sdkmcp-serverthanh-toán-việt-nam

Nỗi đau của lập trình viên Việt Nam với thanh toán AI

Bạn vừa xây dựng một AI agent thông minh: bot bán khoá học, cửa hàng quần áo tự động, hoặc ứng dụng dịch vụ nào đó. Agent này hoạt động tốt, nhưng khi đến bước thu tiền, bạn gặp bế tắc:

Kết quả: bạn phải dừng project hoặc chấp nhận 5-10% phí từ nền tảng trung gian. Điều đó đặc biệt tức cười khi lợi nhuận ròng của sản phẩm nhỏ.

Có cách nào khác không? Có! Và hôm nay chúng ta sẽ nói về nó.

AgentPay VN là gì? Tại sao nó giải quyết được vấn đề?

AgentPay VN là một bộ công cụ open-source (giấy phép MIT) cho phép AI agent thu tiền trực tiếp vào tài khoản ngân hàng thực của bạn mà không cần trung gian, không cần công ty chi nhánh, không phí ẩn.

Gồm:

  1. Python SDK (agentpay-vn): thư viện tích hợp dễ dàng
  2. MCP Server (agentpay-mcp): kết nối với Claude, ChatGPT v.v
  3. VietQR Integration: tạo QR code thanh toán chuyên nghiệp

Điểm khác biệt chính

Tính năng Stripe Momo API AgentPay VN
Hỗ trợ VietQR ❌ ✓ (phức tạp) ✓ (đơn giản)
Thanh toán trực tiếp vào tài khoản ❌ ❌ ✓
Open-source ❌ ❌ ✓
Không giữ tiền ❌ ❌ ✓
Phí thanh toán 2.9% 0.5-1% 0%
Hỗ trợ AI agent Không tự động Thủ công ✓ MCP native

Nhìn vào bảng, AgentPay VN tối ưu cho creator, startup, và các sản phẩm AI nhỏ và vừa ở Việt Nam.

Cách hoạt động: 3 bước đơn giản

Quy trình thanh toán với AgentPay VN chỉ cần 3 bước:

  1. Tạo request thanh toán (create_payment_request)
  2. Gửi checkout URL tới khách hàng (QR code hoặc link)
  3. Chờ xác nhận từ ngân hàng (await_settlement)

Tiền vào thẳng tài khoản bạn. Không bao giờ AgentPay VN giữ một đồng nào—nó chỉ là kênh kết nối.

Cài đặt & Thiết lập trong 5 phút

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

pip install agentpay-vn

Xong! Thế là đủ để sử dụng SDK.

Bước 2: Cài đặt MCP Server (nếu dùng AI agent)

pip install agentpay-mcp

Bước 3: Kết nối với AI (Claude/ChatGPT)

Nếu bạn dùng Claude (qua API hoặc Claude.ai với MCP), thêm config vào file claude_desktop_config.json:

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

Sau đó, Claude có thể gọi các hàm AgentPay như một tool bình thường.

Code thực hành: Tạo thanh toán & chờ settlement

Ví dụ 1: Tạo payment request cơ bản

from agentpay_vn import AgentPayClient

# Khởi tạo client
client = AgentPayClient()

# Tạo request thanh toán
payment = client.create_payment_request(
    amount=299000,  # Giá sản phẩm: 299k VND
    description="Khoá học Python nâng cao",
    merchant_account="0123456789",  # Tài khoản ngân hàng của bạn
    reference_id="order_20250115_001"  # ID đơn hàng riêng
)

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

Giải thích: - amount: Số tiền tính bằng VND - description: Mô tả sản phẩm (hiển thị trong app banking) - merchant_account: Số tài khoản thụ hưởng (của bạn) - reference_id: ID nội bộ để theo dõi đơn hàng

Output:

QR Code URL: https://vietqr.io/api/qr/YOUR_PAYMENT_ID.png
Payment ID: pay_abc123xyz789

Gửi checkout_url cho khách hàng—họ mở bằng ngân hàng app, quét QR hoặc dùng link, rồi thanh toán.

Ví dụ 2: Chờ xác nhận & xử lý settlement

import asyncio
from agentpay_vn import AgentPayClient

async def wait_for_payment(payment_id: str, timeout_seconds: int = 300):
    """
    Chờ khách hàng thanh toán. Timeout mặc định 5 phút.
    Dùng bank feed confirmation để xác minh tiền vào thật sự.
    """
    client = AgentPayClient()

    # Chờ settlement từ ngân hàng
    settlement = await client.await_settlement(
        payment_id=payment_id,
        timeout=timeout_seconds
    )

    if settlement.status == "confirmed":
        print(f"✓ Thanh toán thành công!")
        print(f"  Số tiền: {settlement.amount} VND")
        print(f"  Mã giao dịch: {settlement.transaction_id}")
        print(f"  Thời gian: {settlement.timestamp}")

        # Xử lý logic của bạn (cấp license, gửi product...)
        return True
    else:
        print(f"✗ Thanh toán thất bại hoặc hết timeout.")
        return False

# Sử dụng
async def main():
    success = await wait_for_payment("pay_abc123xyz789")
    if success:
        # Gửi khoá học tới email khách hàng
        send_course_to_email("student@example.com")

asyncio.run(main())

Giải thích: - await_settlement(): Nghe sự kiện từ bank feed. Khi khách hàng thanh toán, ngân hàng confirm thì hàm trả về kết quả - status == "confirmed": Tiền đã vào tài khoản thực sự (không phải "pending") - transaction_id: ID giao dịch từ ngân hàng, dùng để đối soát

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

Giả sử bạn chạy một bot bán khoá học Python. Agent workflow:

1. Khách hàng hỏi: "Bao nhiêu tiền khoá học?"
   → Agent trả lời: "Khoá học Python nâng cao giá 299k VND"

2. Khách hỏi: "Tôi muốn mua!"
   → Agent gọi create_payment_request()
   → Gửi QR code + link thanh toán

3. Khách quét QR, thanh toán qua app banking

4. Ngân hàng confirm, tiền vào tài khoản bạn
   → Bank feed → await_settlement() trả về confirmed

5. Agent nhận signal, gửi ngay link tải khoá học + mật khẩu
   → Khách vui, bạn có tiền 💰

Toàn bộ quy trình tự động 100%, không cần can thiệp thủ công.

Kết nối với Claude (MCP Config chi tiết)

Nếu bạn chạy Claude qua API hoặc Claude Desktop, đây là full config:

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

Claude sẽ tự động nhận diện các tool: - create_payment_request(amount, description, merchant_account, reference_id) - await_settlement(payment_id, timeout) - get_payment_status(payment_id)

Bạn chỉ cần nói: "Tạo QR thanh toán 299k cho Khoá học Python" → Claude tự xử lý.

Nên & Không nên khi dùng AgentPay VN

✓ Nên làm

✗ Không nên làm

Những câu hỏi thường gặp (FAQ)

1. Tiền sẽ vào tài khoản bao lâu sau khi khách thanh toán?

Thường 1-3 phút. Đôi khi lên tới 5 phút nếu ngân hàng lag. AgentPay VN dùng bank feed real-time, nên sẽ notify lập tức khi có giao dịch.

2. Có phí gì không? Có ẩn phí không?

Không có phí nào. AgentPay VN open-source, không lấy commission. Duy nhất bạn phải trả là phí của chính ngân hàng (nếu họ tính)—tuy nhiên hầu hết ngân hàng không tính phí nhận tiền VietQR.

3. Nếu khách hàng quét QR nhưng thanh toán sai số tiền sao?

QR code được set cứng số tiền, nên khách không thể sửa được. Nếu họ quét bằng tay và nhập sai số tiền, await_settlement() sẽ chờ mãi (hoặc timeout). Bạn có thể gửi lại QR hoặc yêu cầu khách thanh toán lại với số tiền đúng.

4. Có thể dùng cho multiple products/prices cùng lúc không?

Có! Mỗi lần gọi create_payment_request() với amount khác nhau, AgentPay sẽ tạo 1 payment request độc lập (có ID riêng). Bạn theo dõi từng cái, tối đa cùng lúc không giới hạn.

5. Nếu khách thanh toán rồi lại muốn hoàn tiền?

AgentPay VN không hỗ trợ hoàn tiền tự động. Bạn cần chủ động chuyển lại tiền cho khách qua ngân hàng bình thường (hoặc dùng VietQR ngược). Nên có quy chính sách hoàn tiền trong ToS của bạn.

Nâng cao: Bảo mật & Best practices

Bảo mật merchant_account

Không bao giờ hardcode số tài khoản:

# ❌ KHÔNG
merchant = "0123456789"

# ✓ ĐÚNG
import os
merchant = os.getenv("AGENTPAY_MERCHANT_ACCOUNT")

Logging & Monitoring

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("agentpay_bot")

async def track_payment(payment_id):
    logger.info(f"Payment initiated: {payment_id}")
    settlement = await client.await_settlement(payment_id)
    logger.info(f"Settlement result: {settlement.status}")

Idempotency: Tránh tạo duplicate payment

# Nếu network bị mất, khách gọi lại "mua hàng"
# Bạn check order_id trước khi tạo payment mới

def safe_create_payment(order_id: str, amount: int):
    # Check xem order này đã có payment chưa
    existing = db.get_payment_by_order(order_id)
    if existing:
        return existing  # Trả lại payment cũ, không tạo mới

    # Nếu chưa, tạo mới
    new_payment = client.create_payment_request(
        amount=amount,
        reference_id=order_id
    )
    db.save_payment(new_payment)
    return new_payment

Tóm tắt nhanh: Checklist khởi động

Kết luận

AgentPay VN giải quyết bài toán thanh toán cho AI agents ở Việt Nam một cách đơn giản, an toàn, và miễn phí. Không cần Stripe, không cần Momo API phức tạp—chỉ cần 3 dòng Python và 1 file config MCP.

Nếu bạn: - 🤖 Đang xây dựng AI agent, chatbot bán hàng - 🇻🇳 Phục vụ khách Việt Nam (VietQR) - 💰 Muốn tiền vào thẳng account (không trung gian) - 📦 Là startup/creator muốn giảm phí

AgentPay VN là giải pháp dành cho bạn.

Bắt đầu ngay hôm nay—chỉ cần 1 lệnh pip install!

Câu hỏi? Issue? Donate? Ghé GitHub repo của dự án. Nó open-source—tự do fork, sửa, dùng theo MIT License.

Chúc bạn bán hàng thành công! 🚀

Bắt đầu →

← Tất cả bài