Tự động thu tiền VietQR cho AI Agent – Thay thế Stripe tại Việt Nam

2026-10-08 · AgentPay VN

aipythonvietqrmcppayment-gateway

Nỗi đau của người bán hàng trực tuyến ở Việt Nam

Hôm nay là thứ hai. Bạn vừa xây xong một bot AI chuyên bán khoá học lập trình trực tuyến – tự động trả lời câu hỏi, gợi ý sản phẩm, và even chốt đơn. Nhưng khi khách hàng muốn thanh toán, bạn phải dừng lại. Tại sao?

Vì Stripe (thanh toán quốc tế chủ yếu) không hỗ trợ VietQR. Bạn phải dùng các gateway "lỏng lẻo" – giữ tiền, chặt phí cao, hoặc xử lý thủ công bằng form PayPal/Momo. Bot AI của bạn, dù thông minh đến mấy, cũng không thể hoàn tất giao dịch một cách tự chủ. Thế là khách bỏ đi, doanh số giảm.

Đây chính là lúc AgentPay VN ra tay.

Giới thiệu AgentPay VN – Giải pháp thanh toán native cho AI

AgentPay VN là một Python SDK mã mở (MIT License) + MCP server cho phép AI agent của bạn trực tiếp thu tiền VietQR mà không phải giữ lại một đồng nào. Tiền chuyển thẳng vào tài khoản ngân hàng của bạn; bank feed (từ ngân hàng) xác nhận hoàn toàn. Đơn giản, nhanh, minh bạch.

Đặc điểm chính: - Không giữ tiền: QR code trỏ trực tiếp đến merchant account của bạn - Bank settlement xác nhận: Không phải chờ callback mập mờ - Hỗ trợ AI native: MCP server tích hợp với Claude, LLaMA, hoặc agent custom - Open-source (MIT): Toàn quyền kiểm soát source code - 3 dòng lệnh: create_payment_request → send_checkout_url → await_settlement

Tại sao không dùng các gateway truyền thống?

MoMo, ZaloPay, và các nền tảng khác rất tốt, nhưng chúng thiết kế cho form web/mobile, không phải cho AI agent lập trình. Khi bot AI của bạn muốn tạo URL thanh toán, chờ khách gửi tiền, rồi nhận biết và kỷ lục hoá – bạn phải viết rất nhiều middleware, webhook, state machine. AgentPay VN đã làm tất cả điều đó sẵn.

Tiêu chí	Stripe	MoMo/ZaloPay	AgentPay VN
Hỗ trợ VietQR	❌	✅ (gián tiếp)	✅ (trực tiếp)
AI Agent-ready	❌	❌	✅
Mã nguồn mở	❌	❌	✅ (MIT)
Giữ tiền	✅ (1-3 ngày)	✅	❌
Bank feed confirm	❌	❌	✅
Setup < 10 phút	❌	❌	✅

Cài đặt AgentPay VN – 2 phút là xong

Bước 1: Cài SDK Python

pip install agentpay-vn

Xong. Không phức tạp, không config external service.

Bước 2: Setup MCP Server (nếu dùng với Claude/AI agent)

install agentpay-mcp

Bước 3: Config thông tin merchant

Sau khi cài đặt, bạn chỉ cần thêm 3 thông tin cơ bản vào env hoặc config file: - MERCHANT_ID: ID của bạn từ dashboard AgentPay VN - BANK_ACCOUNT: Số tài khoản nhận tiền (VietQR) - API_KEY: Token bảo mật

Ở thời điểm này, bạn đã sẵn sàng để code!

Flow cơ bản: Tạo yêu cầu thanh toán → Gửi QR → Đợi hoàn toàn

AgentPay VN hoạt động theo quy trình 3 bước siêu đơn:

Bước 1: Tạo yêu cầu thanh toán

from agentpay_vn import AgentPayVN

# Khởi tạo client
pay_client = AgentPayVN(
    merchant_id="YOUR_MERCHANT_ID",
    api_key="YOUR_API_KEY"
)

# Tạo yêu cầu thanh toán
payment_request = pay_client.create_payment_request(
    amount=499000,  # 499,000 VND
    description="Khoá học Python cho AI agent",
    customer_id="cust_12345",
    metadata={"course_id": "py-ai-101"}  # Custom data
)

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

Giải thích: - amount: Số tiền tính bằng đồng (VND) - description: Mô tả giao dịch (hiển thị trên QR) - customer_id: ID unique của khách (giúp track lịch sử) - metadata: Dữ liệu custom để bot AI xử lý sau (ví dụ: course_id để auto-deliver khoá học)

Bước 2: Gửi URL thanh toán cho khách

# Trong chatbot của bạn
response_to_user = f"""
✅ Tuyệt! Dưới đây là QR code để thanh toán khoá học:

{payment_request.checkout_url}

Scan mã QR bằng app ngân hàng hoặc VietQR để thanh toán 499,000 VND.
Bot sẽ tự động xác nhận khi hoàn tất 🚀
"""

print(response_to_user)

Bước 3: Đợi và xác nhận thanh toán

import asyncio

async def wait_for_payment(payment_id, timeout=300):
    """
    Đợi thanh toán hoàn tất, timeout 5 phút.
    Trả về settlement info khi thành công.
    """
    settlement = await pay_client.await_settlement(
        payment_id=payment_id,
        timeout_seconds=timeout
    )

    if settlement.status == "confirmed":
        print(f"✅ Thanh toán thành công!")
        print(f"   Số tiền: {settlement.amount} VND")
        print(f"   Ngân hàng: {settlement.bank_name}")
        print(f"   Tham chiếu: {settlement.reference_id}")
        return settlement
    else:
        print(f"❌ Thanh toán thất bại: {settlement.status}")
        return None

# Chạy async
settlement = asyncio.run(wait_for_payment(payment_request.id))

if settlement:
    # Auto-deliver khoá học
    deliver_course(customer_id="cust_12345", course_id="py-ai-101")

Các trạng thái của settlement: - pending: Chờ khách thanh toán - confirmed: Bank xác nhận tiền đã vào (bank feed) - failed: Khách hủy hoặc timeout - disputed: Có tranh chấp (rất hiếm)

Tích hợp với AI Agent: Cấu hình MCP cho Claude

Nếu bạn muốn Claude hoặc AI agent khác gọi AgentPay VN trực tiếp, hãy dùng MCP server:

Cấu hình Claude Desktop

Thêm vào file claude_desktop_config.json:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "MERCHANT_ID": "YOUR_MERCHANT_ID",
        "API_KEY": "YOUR_API_KEY",
        "BANK_ACCOUNT": "1234567890"
      }
    }
  }
}

Sau đó, Claude có thể gọi trực tiếp:

User: "Tôi muốn mua khoá học này với giá 599,000 VND."

Claude: "Để tôi tạo link thanh toán cho bạn..."
[Gọi tool: agentpay.create_payment_request]
"Đây là QR code: https://agentpay.servicesai.vn/checkout/pay_abc123xyz"
[Gọi tool: agentpay.await_settlement]
"✅ Tiền đã vào tài khoản! Gửi bạn khoá học ngay..."

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

Bạn là một giáo viên lập trình. Bạn có một chatbot AI (Claude + AgentPay VN) chạy trên website của bạn. Đây là đoạn hội thoại:

User (Khách hàng): "Tôi muốn học Python cho AI. Giá bao nhiêu?"

Bot (Claude): "Khoá 'Python for AI Agent' có giá 599,000 VND. 
Có bao gồm 30 bài video, code examples, và support trong Discord 6 tháng.
Bạn muốn mua không?"

User: "Có! Thanh toán như thế nào?"

Bot: "Một giây..."
[Gọi: create_payment_request(amount=599000, description="Python for AI")]

Bot: "✅ Dưới đây là mã QR thanh toán:
📱 Scan bằng app ngân hàng của bạn
💰 Số tiền: 599,000 VND
📍 Link: https://agentpay.servicesai.vn/checkout/pay_12345

Mình sẽ chờ xác nhận từ ngân hàng..."

[User mở app ngân hàng, scan QR, nhập PIN]
[30 giây sau, bank feed xác nhận]

[Gọi: await_settlement(payment_id=...)]

Bot: "🎉 Tiền đã vào! Chào mừng bạn đến khoá học.
Link đăng ký: https://myplatform.com/courses/py-ai-101?token=xyz
Video đầu tiên đã sẵn sàng. Hãy bắt đầu từ bài 1: Python Basics for AI."

User: "Cảm ơn! Bài đầu hơi khó, câu hỏi..."

Bot: "Không lo! Hãy cho tôi biết chi tiết, tôi sẽ giải thích..."

Kết quả: - ✅ Khách mua một cách tự nhiên (không form phức tạp) - ✅ Bot tự động xác nhận và deliver khoá học - ✅ Bạn nhận tiền 30 giây sau (bank confirm) - ✅ Không phí ẩn, không trung gian

Nếu là Stripe hoặc MoMo, bạn phải tạo: 1. Form riêng → UX kém 2. Webhook server → code phức tạp 3. Job queue để track lịch sử → thêm infra

Với AgentPay VN: bot tự xử lý tất cả trong flow hội thoại. Simple as that.

Nâng cao: Xử lý lỗi, retry, và webhook

Một vài điều cần biết khi deploy production:

Xử lý timeout

from agentpay_vn.exceptions import SettlementTimeoutError

try:
    settlement = await pay_client.await_settlement(
        payment_id=payment_request.id,
        timeout_seconds=300  # 5 phút
    )
except SettlementTimeoutError:
    # Khách không thanh toán trong 5 phút
    # Lưu state, cho phép retry
    save_pending_payment(payment_request.id, expires_at=now+timedelta(hours=24))
    print("Hết thời gian. Bạn có thể thanh toán lại trong vòng 24 giờ.")

Webhook (optional, cho flow không đồng bộ)

Nếu bot của bạn chạy background job, hãy setup webhook:

pay_client.register_webhook(
    event="settlement.confirmed",
    url="https://yourserver.com/webhooks/agentpay",
    secret="your_webhook_secret"
)

Khi thanh toán xác nhận, AgentPay VN sẽ POST tới URL của bạn:

# Trong endpoint của bạn
from agentpay_vn import verify_webhook_signature

@app.post("/webhooks/agentpay")
def handle_settlement_webhook(request: Request):
    payload = request.json()
    signature = request.headers["X-AgentPay-Signature"]

    # Verify webhook authentic
    if not verify_webhook_signature(payload, signature, secret="your_webhook_secret"):
        return {"error": "Invalid signature"}, 401

    payment_id = payload["payment_id"]
    settlement_id = payload["settlement_id"]
    amount = payload["amount"]

    # Auto-deliver hoặc log
    deliver_product(payment_id, amount)
    return {"status": "ok"}

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

✅ Nên làm

Lưu payment_id: Để track lịch sử (database, Redis)
Timeout hợp lý: 5-10 phút là đủ (khách có thể quay lại sau)
Log chi tiết: Để debug nếu settlement fail
Verify settlement: Không trust client-side; luôn gọi await_settlement hoặc check bank feed
Notify khách: "Chờ xác nhận..." → "Tiền đã vào!" → auto-deliver

❌ Không nên làm

Delivery trước khi confirm: Chỉ deliver khi settlement.status == "confirmed"
Cache amount: Luôn fetch từ server (tránh fraud)
Quên test webhook: Webhook là cách duy nhất để handle async settlement
Dùng polling thay vì await_settlement: await_settlement là async-first, hiệu quả hơn
Hardcode merchant_id: Dùng env var hoặc config server

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

1. AgentPay VN có phí không?

AgentPay VN là một open-source SDK, miễn phí 100%. Bạn chỉ trả phí cho bank khi rút tiền (phí chuyển khoản thường = 0-5K VND tùy ngân hàng, hoặc miễn phí nếu > 1 tỷ VND/năm).

2. Tôi cần tài khoản gì để dùng?

Chỉ cần tài khoản ngân hàng có hỗ trợ VietQR (mọi ngân hàng lớn ở Việt Nam đều có). Không cần tài khoản doanh nghiệp hay giấy phép đặc biệt.

3. Làm thế nào để test trước khi deploy?

AgentPay VN có sandbox mode:

pay_client = AgentPayVN(
    merchant_id="test_merchant",
    api_key="test_api_key",
    sandbox=True  # Test mode
)

Trong sandbox, thanh toán là mock – bạn có thể test flow mà không cần tiền thực.

4. Tiền về tài khoản mất bao lâu?

Haystack: - Bank feed xác nhận: 5-30 giây (AgentPay VN nhận từ ngân hàng) - Rút tiền ròng: Tùy ngân hàng, thường T+0 hoặc T+1

Do đó, bạn có thể delivery ngay khi settlement.status == "confirmed" (5-30 giây sau khi khách thanh toán).

5. Nếu khách thanh toán sai số tiền thì sao?

AgentPay VN tự động so sánh:

if settlement.amount != payment_request.amount:
    # Cảnh báo – số tiền không khớp
    # Quyết định refund hoặc accept dựa trên logic của bạn
    handle_amount_mismatch(payment_request, settlement)

Bạn có thể tự động refund hoặc yêu cầu khách thanh toán lại.

Tóm tắt nhanh

AgentPay VN là Python SDK (MIT) + MCP server giúp AI agent thu tiền VietQR trực tiếp
Không giữ tiền, thanh toán xác nhận bằng bank feed, không phí ẩn
3 bước đơn giản: create_payment_request() → gửi checkout_url → await_settlement()
Cài đặt nhanh: pip install agentpay-vn, 3 config var là xong
Perfect cho AI chatbot: MCP-ready, tích hợp dễ với Claude, LLaMA, agent custom
Kịch bản thực tế: Bot bán khoá học, quán cà phê, shop online – tất cả tự động trong chat
Safe để deploy: Có sandbox test mode, webhook, timeout, error handling
Open-source: Kiểm soát code, không vendor lock-in

Bắt đầu ngay hôm nay

Bạn đã sẵn sàng để tự động hóa thanh toán cho AI agent của mình:

Cài SDK: pip install agentpay-vn
Đọc docs: https://agentpay.servicesai.vn/v1/docs
Explore GitHub: https://github.com/phuocdu/agentpay-vn
Deploy: Thêm 3 dòng code vào bot của bạn, test ở sandbox, lên production

Không còn chính phủ gateway nữa. Thanh toán bây giờ là một tính năng của bot, không phải một công việc riêng biệt.

Happy coding! 🚀

Bắt đầu →

← Tất cả bài