Tạo MCP Server Thu Phí: Để Claude Thanh Toán VietQR Ngay Trong Chat

2026-07-21 · AgentPay VN

aipythonmcpvietqragentpay

Tình Huống: Chatbot Thông Minh Cần Nhận Tiền

Bạn vừa phát triển một trợ lý AI chạy trên Claude, giúp khách hàng tìm khoá học, đặt bàn quán cà phê, hay mua sản phẩm số. Nhưng có một vấn đề: khi khách muốn thanh toán, chatbot chỉ biết nói "Hãy chuyển khoản thủ công". Kết quả? 30% khách bỏ ngang, vì quy trình quá rườm rà.

Bạn cần một cách để Claude tạo hoá đơn, gửi link QR code, và xác nhận thanh toán trong cùng một cuộc trò chuyện—mà không cần bạn giữ tiền khách hàng. Đó chính là lúc AgentPay VN + MCP server bước vào.

AgentPay VN Là Gì? (Và Tại Sao Bạn Cần Nó)

AgentPay VN là một SDK Python mã nguồn mở (MIT) cho phép các AI agents—đặc biệt là Claude—tạo yêu cầu thanh toán qua VietQR mà không bao giờ nắm giữ tiền. Thay vào đó:

QR code trỏ thẳng tới tài khoản ngân hàng của bạn (hoặc merchant).
Ngân hàng xác nhận giao dịch qua tính năng bank feed.
Agent nhận thông báo settlement và tiếp tục xử lý logic (gửi khoá học, in hoá đơn, v.v.).

Khác biệt so với cách cũ: - Không cần tích hợp Stripe/PayPal phức tạp cho VN. - Không cần hold tiền trung gian (rủi ro, phức tạp pháp lý). - Tích hợp sẵn với Claude thông qua MCP (Model Context Protocol).

Cài Đặt & Setup Ban Đầu (3 Bước)

Bước 1: Cài SDK

pip install agentpay-vn

Xong. Không cần key bí mật hay OAuth dài dòng lúc này.

Bước 2: Cài MCP Server

agentpay-mcp

MCP server chạy trên máy bạn, cho phép Claude gọi các hàm AgentPay thông qua protocol tiêu chuẩn.

Bước 3: Cấu Hình Claude Desktop / App

Thêm vào file cấu hình MCP (thường là ~/.config/claude-desktop/claude_desktop_config.json trên macOS/Linux, hoặc %APPDATA%\Claude\claude_desktop_config.json trên Windows):

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "args": []
    }
  }
}

Restart Claude Desktop. Xong! Claude giờ có thể gọi các tool AgentPay.

Quy Trình Thanh Toán 3 Bước (Core Flow)

Mỗi giao dịch AgentPay tuân theo quy trình này:

Bước 1: Tạo Yêu Cầu Thanh Toán

from agentpay_vn import AgentPayClient

client = AgentPayClient(
    merchant_id="your_merchant_id",  # Merchant ID từ ngân hàng/TPAY
    api_key="your_api_key"            # API key công khai
)

# Tạo yêu cầu thanh toán
payment_request = client.create_payment_request(
    amount=250000,                     # 250k VND
    description="Khoá học Python nâng cao",
    order_id="order_12345",            # ID unique cho đơn hàng
    customer_email="khach@example.com",
    customer_phone="0901234567"
)

print(f"Payment ID: {payment_request['payment_id']}")
print(f"QR Code URL: {payment_request['qr_code_url']}")
print(f"Checkout URL: {payment_request['checkout_url']}")

Giải thích: - amount: Số tiền khách phải trả (VND). - order_id: ID duy nhất để bạn track đơn hàng sau (có thể là UUID hoặc số sequence). - description: Mô tả hiển thị trên QR code (khách thấy khi quét). - Response trả về payment_id (dùng để check trạng thái) và checkout_url (link khách bấm hoặc QR).

Bước 2: Gửi Checkout URL Cho Khách

Claude gửi link hoặc QR code:

checkout_url = payment_request['checkout_url']

# Gửi message tới khách (trong Claude conversation)
user_message = f"""
Cảm ơn bạn! Để hoàn tất đơn hàng, vui lòng quét mã QR hoặc bấm vào link dưới đây:

🔗 {checkout_url}

Hoặc quét QR code trong app ngân hàng.

Giao dịch sẽ được xác nhận trong vòng 1-2 phút.
"""
print(user_message)

Bước 3: Chờ Xác Nhận Thanh Toán

import time
from agentpay_vn.exceptions import PaymentTimeoutError

# Poll trạng thái (thực tế: lắng nghe bank feed hoặc webhook)
try:
    settlement = client.await_settlement(
        payment_id=payment_request['payment_id'],
        timeout_seconds=300  # Chờ tối đa 5 phút
    )

    print(f"✅ Thanh toán thành công!")
    print(f"Transaction ID: {settlement['transaction_id']}")
    print(f"Amount received: {settlement['amount']} VND")
    print(f"Settled at: {settlement['settled_at']}")

    # Thực hiện logic sau thanh toán
    deliver_course(customer_email=payment_request['customer_email'])
    send_invoice(order_id=payment_request['order_id'])

except PaymentTimeoutError:
    print("❌ Khách hàng chưa thanh toán trong 5 phút.")
    resend_reminder(customer_email=payment_request['customer_email'])

Chú ý: - await_settlement() là non-blocking—nó poll bank feed hoặc lắng nghe webhook. - Nếu quá 5 phút không có giao dịch, nó raise exception; bạn có thể gửi nhắc nhở. - Khi settlement xác nhận, bạn có thể ngay lập tức gửi sản phẩm/khoá học cho khách.

Ví Dụ Đời Thực: Bot Bán Khoá Học Online

Hãy tưởng tượng bạn có một chatbot Claude bán khoá học Python. Đây là flow hoàn chỉnh:

# bot.py
from agentpay_vn import AgentPayClient
import json

client = AgentPayClient(
    merchant_id="MERCHANT_001",
    api_key="pk_live_xxx"
)

COURSES = {
    "python-basics": {"price": 99000, "name": "Python Cơ Bản"},
    "python-advanced": {"price": 250000, "name": "Python Nâng Cao"},
}

def process_course_purchase(course_id: str, customer_email: str):
    """
    Xử lý mua khoá học từ đầu tới cuối.
    """
    if course_id not in COURSES:
        return {"error": "Khoá học không tồn tại"}

    course = COURSES[course_id]

    # 1️⃣ Tạo yêu cầu thanh toán
    payment_req = client.create_payment_request(
        amount=course["price"],
        description=f"Khoá học: {course['name']}",
        order_id=f"order_{course_id}_{int(time.time())}",
        customer_email=customer_email
    )

    print(f"📝 Tạo yêu cầu thanh toán: {payment_req['payment_id']}")
    print(f"🔗 Gửi link: {payment_req['checkout_url']}")

    # 2️⃣ Chờ thanh toán
    try:
        settlement = client.await_settlement(
            payment_id=payment_req['payment_id'],
            timeout_seconds=600  # 10 phút
        )
        print(f"✅ Thanh toán nhận được: {settlement['amount']} VND")

        # 3️⃣ Gửi khoá học
        course_access_token = generate_token(customer_email, course_id)
        send_email(
            to=customer_email,
            subject=f"Chúc mừng! Bạn đã mua {course['name']}",
            body=f"Truy cập khoá học tại: https://learning.example.com?token={course_access_token}"
        )

        return {
            "status": "success",
            "message": f"Khoá học {course['name']} đã được gửi tới {customer_email}!",
            "access_url": f"https://learning.example.com?token={course_access_token}"
        }

    except PaymentTimeoutError:
        print(f"⏱️ Khách chưa thanh toán trong 10 phút")
        return {
            "status": "pending",
            "message": "Bạn có thể quay lại link thanh toán bất cứ lúc nào trong 24 giờ",
            "checkout_url": payment_req['checkout_url']
        }

# Trong conversation, Claude gọi:
result = process_course_purchase(
    course_id="python-advanced",
    customer_email="student@example.com"
)
print(json.dumps(result, indent=2, ensure_ascii=False))

Kịch bản: 1. Khách chat: "Tôi muốn mua khoá Python Nâng Cao." 2. Claude gọi process_course_purchase("python-advanced", "student@example.com"). 3. Hàm tạo QR code, gửi link cho khách. 4. Khách quét QR, chuyển 250k VND từ app ngân hàng. 5. await_settlement() phát hiện giao dịch trong vòng 1-2 phút. 6. Claude tự động gửi email link truy cập khoá học. 7. Xong! Khách đã có khoá học, bạn đã nhận tiền.

Nên Làm Gì, Không Nên Làm Gì

Nên ✅	Không Nên ❌
Lưu `payment_id` để tracking lịch sử	Không bao giờ lưu trữ payment data trên client
Dùng `order_id` unique cho mỗi đơn hàng	Tái sử dụng `order_id` từ đơn hàng khác
Xử lý exception `PaymentTimeoutError` graceful	Không xử lý lỗi timeout (UX tệ)
Gửi email xác nhận sau khi `settlement` confirm	Gửi email trước khi thanh toán thực tế
Cấu hình webhook hoặc bank feed để notification	Poll liên tục (lãng phí resource)
Test với sandbox API trước khi live	Deploy trực tiếp lên production

Nâng Cao: Cấu Hình MCP Server Chi Tiết

Nếu bạn muốn tùy chỉnh MCP server (ví dụ: thêm logging, custom webhook):

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "args": [
        "--merchant-id", "MERCHANT_001",
        "--api-key", "pk_live_xxx",
        "--webhook-url", "https://yourapp.com/webhooks/payment",
        "--log-level", "info"
      ],
      "env": {
        "AGENTPAY_TIMEOUT": "300"
      }
    }
  }
}

Các tham số: - --merchant-id: ID thương nhân từ TPAY hoặc ngân hàng partner. - --api-key: Khoá API công khai (không bao giờ dùng secret key ở client). - --webhook-url: Endpoint của bạn để nhận webhook khi có giao dịch (thay cho polling). - --log-level: Mức log (debug, info, warning, error). - AGENTPAY_TIMEOUT: Timeout mặc định cho await_settlement() (giây).

Câu Hỏi Thường Gặp (FAQ)

1. AgentPay có giữ tiền khách không?

Không. Tiền chuyển thẳng vào tài khoản ngân hàng của merchant (bạn). AgentPay chỉ giúp tạo QR code, xác nhận giao dịch—không nắm giữ tiền nào. Điều này tránh rủi ro pháp lý và phức tạp kiểm toán.

2. Cần merchant account hay ngân hàng special gì không?

Chỉ cần tài khoản ngân hàng thường + đăng ký TPAY hoặc partner của AgentPay. Không cần công ty lớn hay account kinh doanh đặc biệt. Nếu bạn có tài khoản cá nhân ở Vietcombank, Techcombank, BIDV, v.v., có thể dùng (tuỳ TPAY).

3. Nếu khách chưa thanh toán sau 24 giờ thì sao?

QR code vẫn hợp lệ trong 24 giờ. Bạn có thể: - Gửi email nhắc nhở sau 1 giờ (nếu await_settlement() timeout). - Giữ checkout_url để khách quay lại sau. - Sau 24 giờ, tạo yêu cầu thanh toán mới (nếu khách muốn).

4. Có thể bán nhiều sản phẩm cùng lúc không (bundle)?

Có. Tạo một create_payment_request() duy nhất với tổng amount, và description liệt kê sản phẩm. Lúc settlement confirm, bạn biết khách đã mua bundle nào dựa trên order_id.

Tóm Tắt Nhanh

🚀 AgentPay VN = Python SDK mã nguồn mở để AI agents tạo thanh toán VietQR.
💰 Không giữ tiền: QR → tài khoản merchant → xác nhận ngân hàng.
🔗 3 bước đơn giản: create_payment_request() → gửi URL → await_settlement().
🤖 Tích hợp Claude qua MCP server—Claude tạo hoá đơn, xác nhận thanh toán trong chat.
🏪 Use case: Bán khoá học, đặt bàn, shop online—bất kỳ chatbot AI nào cần thu phí.
⚡ Setup 2 phút: pip install agentpay-vn + cấu hình MCP + xong.
🛡️ An toàn: Không cần lưu payment data, không giữ tiền trung gian, tuân theo PCI compliance.

Bước Tiếp Theo

Bạn đã hiểu cách tạo MCP server thu phí với Claude. Bây giờ:

Cài AgentPay VN: bash pip install agentpay-vn
Đọc tài liệu chi tiết: - 📖 Docs & API Reference - 🐙 GitHub Repository
Chạy demo: bash agentpay-mcp # Khởi động MCP server Sau đó mở Claude Desktop, nó sẽ phát hiện tool AgentPay.
Bắt đầu build: Viết logic sản phẩm của bạn, dùng các ví dụ trên làm template.

Chúc bạn thành công! 🎉 Nếu có câu hỏi, hãy vào GitHub discussions hoặc docs.

Bắt đầu →

← Tất cả bài