Thêm thanh toán VietQR cho AI agent chỉ trong 10 phút

2026-07-03 · AgentPay VN

aipythonvietqragentpaymcp

Bạn đang xây dựng bot AI nhưng còn thiếu một mảnh ghép quan trọng

Hình dung: bạn vừa hoàn thành một chatbot bán khoá học online; khách hàng gõ "mua khoá Python" → bot phản hồi ngay, tuy nhiên... khi tới bước thanh toán, bạn lại phải dựa vào Stripe hoặc Paypal, hoặc còn tệ hơn, phải kêu khách chuyển tiền thủ công qua ngân hàng. Bữa đó, từ "mua ngay" đến "có hàng trong tay" lại thành 1-2 ngày vì bạn phải xác nhận thủ công. Con số này không thể chấp nhận được trong thời đại AI.

Câu hỏi đơn giản mà không ai trả lời: tại sao AI agent của bạn không thể nhận thanh toán trực tiếp qua VietQR, vào luôn tài khoản ngân hàng, mà không cần bất kỳ trung gian nào?

AgentPay VN sinh ra để giải quyết đúng bài toán này—và bạn sẽ ngạc nhiên khi biết setup chỉ cần 10 phút.

Vấn đề: tại sao thanh toán lại khó với AI agent Việt Nam?

Có ba thách thức:

Hầu hết SDK thanh toán toàn cầu không hỗ trợ VietQR—bạn bị ép dùng giải pháp quốc tế, bị phí cao, bị delay.
Integrating thanh toán thường mất 2-3 ngày: cấu hình webhook, quản lý state, xử lý timeout, kiểm tra reconciliation. Quá phức tạp cho một startup.
AI agent cần quyền tự động: nó phải tự tạo link thanh toán, tự chờ xác nhận từ ngân hàng, tự kích hoạt hành động tiếp theo (gửi khoá, unlock feature...) mà không cần can thiệp người.

AgentPay VN xoá sạch ba vấn đề này.

AgentPay VN: SDK Python siêu đơn giản cho AI agent

Trước tiên, hiểu AgentPay VN là gì:

Open-source, MIT License: code mở, bạn kiểm tra được, deploy ở đâu cũng được.
Python SDK + MCP Server: tích hợp với Claude, với bất kỳ LLM nào hỗ trợ MCP.
Không giữ tiền: QR code đã sinh ra trỏ thẳng vào tài khoản ngân hàng của bạn. Tiền vào luôn, không qua trung gian, không risk.
Bank feed tự động confirm: sau khi giao dịch về ngân hàng, AgentPay pull bank feed để xác nhận thanh toán (không phải chờ webhook từ bên thứ ba).

Cơ chế hoạt động: 3 bước siêu sạch

create_payment_request() 
    ↓ 
    (tạo QR, lưu metadata) 
    ↓ 
send_checkout_url()
    ↓
    (gửi link cho khách)
    ↓
await_settlement()
    ↓
    (chờ confirm từ bank feed)
    ↓
    ✅ Giao dịch xác nhận → hành động tiếp theo (tự động)

Cách setup: đúng 10 phút

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

pip install agentpay-vn

Xong, thế thôi. Không cần cấu hình secret key phức tạp, không cần OAuth flow.

Bước 2: Code đơn giản—tạo request thanh toán

from agentpay_vn import AgentPay

# Khởi tạo client (dùng thông tin ngân hàng của bạn)
pay_client = AgentPay(
    bank_account="1234567890",          # Số TK ngân hàng
    bank_code="970422",                 # Mã ngân hàng (VCB, TCB, ...)
    account_name="NGUYEN VAN A"         # Tên tài khoản
)

# Tạo request thanh toán (ví dụ: khách mua khoá học)
payment_req = pay_client.create_payment_request(
    amount=299000,                      # 299k VND
    description="Khoá Python Cơ Bản",  # Mô tả
    reference_id="order_12345",         # ID đơn hàng (của bạn)
    order_metadata={
        "customer_email": "khach@example.com",
        "course_id": "py101",
        "expiry_minutes": 15            # QR hết hạn sau 15 phút
    }
)

# payment_req chứa:
# {
#   "qr_code": "00020101...",           (VietQR string, dùng để render QR)
#   "checkout_url": "https://...",     (link để share hoặc embed)
#   "request_id": "req_abc123",        (ID để tracking)
#   "expires_at": "2024-01-15T10:30Z"  (thời điểm hết hạn)
# }

print(f"Gửi link này cho khách: {payment_req['checkout_url']}")

Giải thích từng dòng: - create_payment_request(): tạo một yêu cầu thanh toán duy nhất, liên kết với reference_id (đơn hàng của bạn). - qr_code: chuỗi VietQR tiêu chuẩn—bạn có thể render bằng thư viện QR bất kỳ (vd: qrcode package). - order_metadata: lưu thông tin bạn muốn link với giao dịch này—sau này dùng để biết "ai mua, cái gì, lúc nào". - expiry_minutes: QR sẽ không còn hiệu lực sau 15 phút (tránh thanh toán trùng, tránh chaos).

Bước 3: Chờ xác nhận từ ngân hàng

import asyncio
from agentpay_vn import AgentPay

async def wait_for_payment(pay_client, request_id, timeout_seconds=900):
    """
    Chờ tới khi giao dịch được xác nhận từ bank feed.

    Tham số:
      - request_id: ID request từ create_payment_request()
      - timeout_seconds: tối đa chờ bao lâu (default: 15 phút)

    Return:
      - Nếu thành công: dict {"status": "settled", "transaction_id": "...", ...}
      - Nếu timeout/fail: raise exception
    """
    settlement = await pay_client.await_settlement(
        request_id=request_id,
        timeout_seconds=timeout_seconds,
        poll_interval_ms=2000  # Check mỗi 2 giây, để detect payment nhanh
    )

    # Nếu đến đây, thanh toán đã confirmed từ bank feed
    print(f"✅ Thanh toán xác nhận! Transaction ID: {settlement['transaction_id']}")
    print(f"   Số tiền: {settlement['amount']} VND")
    print(f"   Thời gian: {settlement['settled_at']}")

    # Lúc này, bạn có thể tự động:
    # - Gửi khoá học cho khách
    # - Unlock feature trong app
    # - Ghi log vào database
    # - Notify khách qua email/SMS

    return settlement

# Sử dụng
if __name__ == "__main__":
    pay_client = AgentPay(...)
    payment_req = pay_client.create_payment_request(...)

    settlement = asyncio.run(
        wait_for_payment(pay_client, payment_req["request_id"])
    )

Chú ý quan trọng: - await_settlement() là async function—nó không block thread, AI agent có thể xử lý requests khác trong khi chờ. - poll_interval_ms=2000: mỗi 2 giây, SDK sẽ check bank feed một lần. Nhanh hơn, nhưng không tốn resource. - Nếu khách không thanh toán trong vòng timeout, exception được raise—bạn có thể catch và gửi reminder.

Integrating với Claude (hoặc LLM khác) qua MCP

Bước này cho phép Claude tự gọi các hàm AgentPay—không cần bạn viết code webhook.

Cài đặt MCP Server

pip install agentpay-mcp

Cấu hình Claude (Claude Desktop)

Sửa file ~/.claude_desktop_config.json (macOS/Linux) hoặc %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": [
        "-m",
        "agentpay_mcp",
        "--bank-account",
        "1234567890",
        "--bank-code",
        "970422",
        "--account-name",
        "NGUYEN VAN A"
      ]
    }
  }
}

Khi này, Claude sẽ có 3 tool tự động: 1. agentpay_create_payment_request — tạo request thanh toán 2. agentpay_send_checkout_url — gửi link (SMS/email integration) 3. agentpay_await_settlement — chờ settlement

Claude sẽ tự quyết định gọi tool nào, lúc nào, mà không cần prompt đặc biệt.

Kịch bản đời thực: Bot bán khoá học online

Giả sử bạn chạy một lớp Python Cơ Bản với giá 299k. Đây là flow:

Khách: "Mình muốn mua khoá Python"

Bot (Claude + AgentPay): 1. Claude nhận request → gọi agentpay_create_payment_request(amount=299000, description="Khoá Python Cơ Bản") 2. AgentPay trả về QR + checkout_url 3. Claude render QR bằng terminal hoặc gửi link: "Scan QR này hoặc click link để thanh toán: https://agentpay.servicesai.vn/checkout/..." 4. Bot gọi agentpay_await_settlement(request_id) → chờ trong background (không block) 5. Khách scan QR, thanh toán 299k vào tài khoản bot (khoảng 2-5 giây) 6. AgentPay nhận confirm từ bank feed → settlement callback 7. Bot tự động: gửi email với link khoá học, tạo tài khoản học viên, enable access trên LMS 8. Khách nhận: "✅ Thanh toán thành công! Bạn đã được cấp quyền truy cập khoá học. Vào đây: [link LMS]"

Toàn bộ quá trình: < 30 giây, không cần bot chủ động confirm, không cần người quản lý xác nhận.

So sánh: AgentPay VN vs các cách cũ

Tiêu chí	AgentPay VN	Stripe/Paypal	Ngân hàng thủ công
Setup time	10 phút	2-3 ngày	N/A
Hỗ trợ VietQR	✅ Native	❌ Phải qua gateway third-party	✅ Native
Phí	0% (bạn tự handle)	2-3% + fixed fee	0%
Tài khoản mà tiền vào	Của bạn (trực tiếp)	Trung gian collect rồi chuyển	Của bạn (thủ công confirm)
AI agent tự động hành động	✅ Async polling	⚠️ Webhook nhưng delay	❌ Không thể
Tốc độ confirm	2-5 giây	5-15 giây	Tùy người confirm (giờ hành chính)
Open-source	✅ MIT	❌ Proprietary	N/A

FAQ: Câu hỏi bạn đang nghĩ

1. AgentPay có giữ tiền của tôi không?

Không. Tiền ghi thẳng vào tài khoản ngân hàng của bạn. Không có wallet trung gian, không có reserve, không có hold period. AgentPay chỉ là lớp integration giữa AI agent của bạn và VietQR.

2. Làm sao AgentPay biết giao dịch đã about settled?

AgentPay pull bank feed (danh sách giao dịch) từ ngân hàng của bạn. Khi bạn thanh toán vào QR, sau 2-5 giây, giao dịch xuất hiện trong feed. SDK so khớp reference_id + amount → confirm settlement. Không phụ thuộc vào webhook của bên thứ ba.

3. Nếu AI agent offline, request thanh toán sẽ mất không?

Request được lưu trong database AgentPay (hoặc database của bạn nếu self-host). Khi agent quay lại online, nó có thể query lại status hoặc await_settlement() từ đó ra. QR code vẫn valid tới hết expires_at, khách vẫn có thể scan và thanh toán.

4. Có thể integratingMCP server này vào agent framework khác (LangChain, AutoGen...) không?

Có. MCP là standard mở. Nếu framework của bạn hỗ trợ MCP, bạn cấu hình theo docs của framework. Nếu không hỗ trợ, bạn dùng SDK Python trực tiếp (code ở trên) mà không cần MCP.

Những việc nên/không nên khi dùng AgentPay VN

✅ NÊN: - Dùng order_metadata để lưu thông tin context (khách nào, mua cái gì, UX intent) - Tính expiry_minutes dựa trên workflow của bạn (khoá học: 15-30 phút, quán cà phê: 5 phút) - Handle timeout exception từ await_settlement() → gửi reminder hoặc refund - Self-host bank feed pull nếu latency quan trọng (muốn confirm < 2 giây)

❌ KHÔNG NÊN: - Tái sử dụng request_id cho multiple requests (mỗi request = unique ID) - Trust client-side QR validation (luôn confirm từ backend) - Quên ghi reference_id → sẽ khó reconcile sau - Để expires_at quá dài (tránh QR cũ vẫn valid)

Tóm tắt nhanh: Bắt đầu trong 10 phút

Cài SDK: pip install agentpay-vn
3 bước code: create_payment_request() → send_checkout_url() → await_settlement()
Không setup phức tạp: không secret key rotation, không OAuth, không webhook listening
Tiền vào tài khoản của bạn: không giữ, không delay, không phí trung gian
AI agent tự động: Claude hoặc LLM khác tự quyết định khi nào tạo QR, khi nào confirm, khi nào unlock feature
Open-source: bạn có thể fork, modify, self-host hoàn toàn

Bước tiếp theo: Bắt tay vào code

Cài đặt: pip install agentpay-vn
Clone example repo: https://github.com/phuocdu/agentpay-vn (folder examples/ có templates sẵn)
Đọc docs đầy đủ: https://agentpay.servicesai.vn/v1/docs (API reference, troubleshooting, advanced config)
Deploy MCP server: nếu bạn dùng Claude, làm theo bước config ở trên
Kiểm thử sandbox: AgentPay hỗ trợ test mode—không cần giao dịch thật để debug

Lợi ích của việc bắt đầu ngay: - Bot của bạn sẽ xử lý thanh toán tự động, loại bỏ bottleneck thủ công - Khách có trải nghiệm instant (không chờ confirm 1-2 ngày) - Bạn tiết kiệm 2-3% phí so với Stripe/Paypal - Code hoàn toàn dưới quyền kiểm soát của bạn—không vendor lock-in

AI agent của bạn giờ đây không chỉ hội thoại, mà còn bán hàng. Đó chính là sức mạnh thực sự.

Bắt đầu →

← Tất cả bài