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

2026-08-03 · AgentPay VN

aipythonmcpvietqragentpay

Bạn đang gặp bài toán nào?

Tưởng tượng bạn có một chatbot AI bán khoá học online, hoặc một agent tự động hỗ trợ khách hàng quán cà phê. Khách hàng muốn thanh toán ngay trong cuộc trò chuyện, nhưng bạn lại phải dừng lại để chuyển hướng đến một trang thanh toán bên ngoài, hoặc còn tệ hơn — phải xây dựng toàn bộ hệ thống thanh toán từ đầu?

Bây giờ hãy tưởng tượng một tình huống khác: bạn lo lắng về bảo mật. Nếu tích hợp cổng thanh toán vào bot, hệ thống của bạn có phải lưu trữ các thông tin thanh toán nhạy cảm không? Rủi ro bảo mật lập tức tăng gấp bội.

AgentPay VN sinh ra để giải quyết chính xác những bài toán này.

AgentPay VN là gì?

AgentPay VN là một SDK Python mã nguồn mở (MIT) kết hợp với MCP server, cho phép AI agent của bạn thu thập thanh toán VietQR một cách hoàn toàn an toàn.

Điểm mấu chốt: AgentPay KHÔNG bao giờ giữ tiền. QR code sinh ra sẽ trỏ thẳng vào tài khoản ngân hàng của merchant (người bán), và ngân hàng sẽ tự động xác nhận khi thanh toán hoàn tất. Bạn không phải lo về PCI compliance, tokenization, hay bất kỳ vấn đề bảo mật phức tạp nào.

Tại sao lại chọn AgentPay VN thay vì các giải pháp khác?

Tính năng	AgentPay VN	Cổng thanh toán truyền thống	Tự xây dựng
Thời gian tích hợp	10 phút	2-3 tuần	1-3 tháng
Bảo mật (không giữ tiền)	✅ Hoàn toàn	❌ Phải lưu tiền tạm	❌ Cần xây dựng
Chi phí hạ tầng	Miễn phí (open-source)	$100-500/tháng	$1000+
Tích hợp với AI agent	✅ Dễ dàng (MCP)	⚠️ Phức tạp	❌ Rất khó
Hỗ trợ VietQR	✅ Native	⚠️ Thường chỉ NAPAS	✅ Nếu bạn xây

Cài đặt — Chỉ cần 1 lệnh

pip install agentpay-vn

Đó là tất cả! SDK đã sẵn sàng trong môi trường Python của bạn.

Nếu bạn muốn sử dụng AgentPay như một MCP server (để tích hợp với Claude hoặc các agent framework khác), cài thêm:

pip install agentpay-mcp

Quy trình 3 bước cơ bản

AgentPay VN hoạt động theo một quy trình rất đơn giản:

Tạo yêu cầu thanh toán (create_payment_request)
Gửi URL checkout cho khách (send_checkout_url)
Chờ xác nhận thanh toán từ ngân hàng (await_settlement)

Code thực tế: Ví dụ đầu tiên

Dưới đây là một ví dụ hoàn chỉnh — một bot bán khoá học trực tuyến:

from agentpay_vn import PaymentClient, PaymentRequest
import asyncio

# Khởi tạo client với thông tin merchant
payment_client = PaymentClient(
    merchant_id="MCH_KHOAHOC_123",
    account_name="Công ty Khoá học AI Việt",
    account_number="1234567890",  # Số tài khoản ngân hàng
    bank_code="970418"  # Mã SWIFT/BIN của ngân hàng (VD: TPBank = 970418)
)

# Bot nhận yêu cầu từ khách hàng
async def handle_course_purchase(customer_id: str, course_name: str, price_vnd: int):
    # Bước 1: Tạo yêu cầu thanh toán
    payment_request = PaymentRequest(
        order_id=f"ORD_{customer_id}_{course_name}",
        amount=price_vnd,
        description=f"Thanh toán khóa học: {course_name}",
        metadata={"customer_id": customer_id, "course": course_name}
    )

    # Tạo QR code và lấy URL checkout
    checkout_response = await payment_client.create_payment_request(payment_request)
    checkout_url = checkout_response["checkout_url"]
    qr_code_data = checkout_response["qr_code"]  # Dữ liệu VietQR

    print(f"🎓 Khách hàng {customer_id} vui lòng quét mã QR:")
    print(f"Giá: {price_vnd:,} VND")
    print(f"URL: {checkout_url}")

    # Bước 2 & 3: Gửi URL và chờ thanh toán (timeout 30 phút)
    try:
        settlement = await payment_client.await_settlement(
            order_id=payment_request.order_id,
            timeout_seconds=1800  # 30 phút
        )

        # Thanh toán thành công!
        print(f"✅ Thanh toán thành công! Mã giao dịch: {settlement['transaction_id']}")
        print(f"💰 Số tiền: {settlement['amount']} VND")

        # Cấp quyền truy cập khoá học
        await grant_course_access(customer_id, course_name)

        return {"status": "success", "transaction_id": settlement["transaction_id"]}

    except asyncio.TimeoutError:
        print(f"⏱️ Hết thời gian chờ thanh toán cho khách {customer_id}")
        return {"status": "timeout"}

# Gọi hàm
asyncio.run(handle_course_purchase("CUST_001", "Python_Advanced", 299000))

Giải thích từng phần:

PaymentClient: Đối tượng chính để giao tiếp với hệ thống. Bạn cần cung cấp merchant_id, tên tài khoản, số tài khoản, và mã ngân hàng.
PaymentRequest: Đại diện cho một yêu cầu thanh toán. Trường metadata cho phép bạn lưu trữ dữ liệu tùy chỉnh (ví dụ: ID khách hàng, tên khoá học).
create_payment_request(): Sinh ra QR code và trả về checkout_url (để khách có thể quét bằng điện thoại) và qr_code (để bạn hiển thị trong bot).
await_settlement(): Chờ cho đến khi ngân hàng xác nhận thanh toán. Hàm này là async — nó không block thread chính, cho phép bot xử lý các yêu cầu khác.

Tích hợp với MCP Server (cho Claude & các AI agent)

Nếu bạn đang dùng Claude hoặc một agent framework hỗ trợ MCP (Model Context Protocol), hãy cấu hình AgentPay như một tool:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "args": [
        "--merchant-id", "MCH_KHOAHOC_123",
        "--account-name", "Công ty Khoá học AI Việt",
        "--account-number", "1234567890",
        "--bank-code", "970418"
      ],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Sau khi cấu hình, Claude sẽ có thể tự động gọi các hàm thanh toán mà không cần bạn can thiệp. Ví dụ, khi khách nói "Tôi muốn mua khóa học Python hôm nay", Claude có thể:

Hiểu ý định của khách
Tự động gọi create_payment_request
Gửi QR code cho khách
Chờ await_settlement và tự động cấp quyền truy cập

Tất cả mà bạn không phải viết một dòng logic xử lý đặc biệt.

Ví dụ kịch bản đời thực: Quán cà phê tự phục vụ

Hãy tưởng tượng bạn có một bot Telegram/Messenger cho quán cà phê "Cà Phê AI":

Khách: "Cho tôi 1 cà phê espresso và 1 bánh croissant"
Bot: "Được! Tổng cộng 85,000 VND. Vui lòng quét mã QR này để thanh toán."
[Bot hiển thị mã QR VietQR]
Khách: [Quét mã bằng app ngân hàng]
Bot (sau 3 giây): "✅ Cảm ơn! Đơn hàng của bạn sẽ được chuẩn bị. Mã đơn: #ORD_2024_001"

Code cho kịch bản này:

from agentpay_vn import PaymentClient, PaymentRequest
import asyncio

payment_client = PaymentClient(
    merchant_id="CAFE_AI_001",
    account_name="Cà phê AI Việt Nam",
    account_number="9876543210",
    bank_code="970403"  # Agribank
)

async def process_cafe_order(customer_phone: str, items: list, total_price: int):
    """Xử lý đơn hàng cà phê với thanh toán QR"""

    # Tạo ID đơn hàng
    order_id = f"CAFE_{customer_phone}_{int(asyncio.get_event_loop().time())}"

    # Tạo yêu cầu thanh toán
    payment_req = PaymentRequest(
        order_id=order_id,
        amount=total_price,
        description=f"Đơn hàng: {', '.join(items)}",
        metadata={
            "customer_phone": customer_phone,
            "items_count": len(items),
            "type": "cafe"
        }
    )

    # Tạo QR code
    response = await payment_client.create_payment_request(payment_req)

    print(f"\n📦 ĐƠN HÀNG MỚI")
    print(f"Khách: {customer_phone}")
    print(f"Sản phẩm: {', '.join(items)}")
    print(f"Tổng tiền: {total_price:,} VND")
    print(f"\nVui lòng quét mã QR: {response['qr_code']}\n")

    # Chờ khách thanh toán (timeout 10 phút cho cà phê)
    try:
        settlement = await payment_client.await_settlement(
            order_id=order_id,
            timeout_seconds=600
        )
        print(f"✅ THANH TOÁN THÀNH CÔNG")
        print(f"Mã giao dịch: {settlement['transaction_id']}")
        print(f"Đơn hàng {order_id} đang được chuẩn bị...\n")
        return True
    except asyncio.TimeoutError:
        print(f"⚠️ Khách {customer_phone} chưa thanh toán. Huỷ đơn.\n")
        return False

# Sử dụng
asyncio.run(process_cafe_order(
    "0912345678",
    ["Espresso", "Bánh Croissant"],
    85000
))

Nâng cao: Theo dõi nhiều đơn hàng cùng lúc

Nếu bot bạn nhận nhiều đơn hàng đồng thời (hoàn toàn bình thường với một quán cà phê bận rộn), hãy sử dụng asyncio.gather():

import asyncio
from agentpay_vn import PaymentClient

# Danh sách đơn hàng
orders = [
    {"phone": "0912345678", "items": ["Latte", "Bánh"], "price": 75000},
    {"phone": "0987654321", "items": ["Cappuccino"], "price": 45000},
    {"phone": "0901234567", "items": ["Americano", "Kem"], "price": 65000},
]

async def handle_all_orders():
    tasks = [
        process_cafe_order(order["phone"], order["items"], order["price"])
        for order in orders
    ]
    results = await asyncio.gather(*tasks)
    print(f"\n📊 Tóm tắt: {sum(results)}/{len(orders)} đơn hàng thanh toán thành công")

asyncio.run(handle_all_orders())

AgentPay VN được thiết kế để xử lý tình huống này một cách hiệu quả.

Danh sách kiểm tra: Nên làm / Không nên làm

✅ Nên: - Sử dụng metadata để lưu trữ thông tin đơn hàng (khách hàng, sản phẩm, địa chỉ). - Gọi await_settlement() trong một task async để không block bot chính. - Xử lý asyncio.TimeoutError để có logic fallback (ví dụ: huỷ đơn). - Lưu transaction_id từ settlement để audit và reconciliation. - Test với số tiền nhỏ trước (ví dụ: 10,000 VND) để đảm bảo workflow.

❌ Không nên: - Gọi await_settlement() mà không timeout — bot sẽ bị treo nếu khách không thanh toán. - Giữ lại tiền trong hệ thống của bạn. AgentPay gửi trực tiếp vào tài khoản ngân hàng. - Bỏ qua kiểm tra merchant_id và bank_code. Sai một ký tự sẽ gây lỗi. - Công khai account_number trong code. Dùng biến môi trường (os.getenv()).

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

1. Tiền thanh toán đi đâu? Có an toàn không?

Tiền chuyển trực tiếp vào tài khoản ngân hàng của bạn (merchant) thông qua hệ thống VietQR của ngân hàng. AgentPay không bao giờ chạm vào tiền. Bạn không phải lo PCI compliance hay bảo mật dữ liệu thẻ tín dụng.

2. Mất bao lâu để tiền về tài khoản?

Thường 1-5 phút sau khi khách thanh toán. Tất cả phụ thuộc vào ngân hàng của khách. AgentPay sẽ thông báo ngay khi nhận xác nhận từ ngân hàng.

3. Phí giao dịch bao nhiêu?

AgentPay VN hoàn toàn miễn phí (mã nguồn mở MIT). Bạn chỉ phải trả phí giao dịch cho ngân hàng của mình (thường 0-3,000 VND per transaction, hoặc 0% tùy gói).

4. Nếu bot bị lỗi giữa chừng thì sao?

Vì QR code trỏ trực tiếp vào tài khoản ngân hàng, dù bot bị lỗi, khách vẫn có thể thanh toán bình thường. Bạn có thể await_settlement() lại lần sau. Không tiền mất, không dữ liệu mất.

Tóm tắt nhanh

AgentPay VN = SDK Python + MCP server, cho phép AI agent thu thập thanh toán VietQR.
Không giữ tiền: QR trỏ vào tài khoản ngân hàng merchant, ngân hàng xác nhận settlement.
3 bước: create_payment_request() → gửi URL → await_settlement().
Cài đặt: pip install agentpay-vn (10 giây).
An toàn: Không cần lưu dữ liệu nhạy cảm, không PCI compliance, không rủi ro bảo mật.
Thích hợp cho: Bot bán khoá học, quán cà phê, shop online, bất kỳ agent nào cần nhận tiền.
Tích hợp MCP: Tự động hóa toàn bộ flow với Claude hoặc agent khác mà không cần code thêm.

Bắt đầu ngay hôm nay

Bạn chỉ cần 3 phút để cài đặt:

pip install agentpay-vn

Rồi copy ví dụ code ở trên, điền thông tin merchant của bạn (số tài khoản, mã ngân hàng), và chạy!

📚 Tài liệu chi tiết: https://agentpay.servicesai.vn/v1/docs

🔧 Mã nguồn & issue tracker: https://github.com/phuocdu/agentpay-vn

Nếu có câu hỏi, hãy tạo issue trên GitHub hoặc liên hệ qua tài liệu. Team AgentPay VN luôn sẵn sàng hỗ trợ!

Happy coding! 🚀

Bắt đầu →

← Tất cả bài