Tạo MCP Server Thu Phí: Claude Nhận Tiền Trực Tiếp Trong Chat

2026-06-16 · AgentPay VN

aipythonmcpvietqrthanh-toán

Bài Toán Thực Tế: Khi Chatbot Cần "Nhân Loại Hoá" Hành Động Thanh Toán

Hãy tưởng tượng: bạn đang chạy một cửa hàng bán khoá học online. Claude (hoặc bất kỳ AI agent nào) trò chuyện với khách hàng, giới thiệu khóa học, và... rồi sao? Chuyển khách sang trang thanh toán bên ngoài? Khách bỏ cuộc.

Như một nhân viên bán hàng thực thụ, agent của bạn cần thu tiền ngay lập tức, không rời khỏi cuộc hội thoại. Đó chính là giá trị của MCP server có tích hợp thanh toán. Và AgentPay VN là cách giải quyết vấn đề này—đơn giản, an toàn, và không bao giờ giữ tiền của bạn.

AgentPay VN: Thanh Toán Mà Không Có "Người Trung Gian"

AgentPay VN là một SDK Python mã nguồn mở (MIT) kết hợp với MCP server, cho phép AI agents tạo yêu cầu thanh toán VietQR và chờ đợi xác nhận từ ngân hàng.

Điểm khác biệt quan trọng: - ✅ Không giữ tiền: Mã QR trỏ trực tiếp vào tài khoản ngân hàng của merchant - ✅ Xác nhận tự động: Bank feed từ ngân hàng (Vietcombank, Techcombank, v.v.) xác nhận thanh toán ngay - ✅ Tích hợp seamless: Chỉ 3 dòng logic chính để tạo, gửi, và xác nhận - ✅ Chạy offline: MCP server chạy trên máy của bạn, không phụ thuộc dịch vụ bên thứ ba

Cài Đặt & Setup Nhanh Gọn

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

pip install agentpay-vn

Và MCP server:

pip install agentpay-mcp

Bước 2: Cấu Hình AgentPay với Claude

Tạo file mcp-servers.json (hoặc cập nhật cấu hình Claude của bạn):

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "args": [
        "--bank-code",
        "970406",
        "--account-number",
        "0123456789",
        "--account-name",
        "Cua Hang ABC",
        "--api-key",
        "your-bank-api-key-here"
      ]
    }
  }
}

Giải thích tham số: - bank-code: Mã ngân hàng (ví dụ: 970406 = Techcombank) - account-number: Số tài khoản nhận tiền - account-name: Tên chủ tài khoản - api-key: Token để kết nối với ngân hàng (xin từ ngân hàng hoặc dịch vụ fintech)

Quy Trình 3 Dòng: Từ Yêu Cầu Đến Thanh Toán

AgentPay VN đơn giản hóa luồng thanh toán thành ba bước:

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

from agentpay_vn import PaymentRequest

# Khách muốn mua khóa học "Python từ 0 đến 1" giá 299.000 VNĐ
payment = PaymentRequest(
    amount=299000,
    description="Khóa học Python từ 0 đến 1",
    reference_id="order_12345",
    customer_name="Nguyễn Văn A",
    customer_phone="0912345678"
)

print(payment)
# Kết quả: PaymentRequest(id='req_xyz', status='pending', ...)

Giải thích: - amount: Số tiền tính bằng VNĐ (bỏ dấu chấm phân cách) - description: Mô tả sản phẩm/dịch vụ (hiện trên hóa đơn) - reference_id: ID đơn hàng của bạn (dùng để tracking) - customer_*: Thông tin khách (tùy chọn nhưng khuyến khích)

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

# Tạo mã QR và URL checkout
checkout_url = payment.generate_checkout_url()
qr_code_base64 = payment.generate_qr_code()  # QR code dạng hình ảnh

# Gửi cho Claude để hiển thị cho khách
print(f"Khách vui lòng quét mã QR hoặc vào: {checkout_url}")
print(f"<img src='data:image/png;base64,{qr_code_base64}' />")

Điểm chú ý: - QR code trỏ trực tiếp vào tài khoản ngân hàng của bạn (VietQR format) - Khách có thể thanh toán bằng bất kỳ ứng dụng ngân hàng nào hỗ trợ VietQR - Không cần redirect, không cần xác thực thêm

Bước 3: Chờ Xác Nhận Từ Ngân Hàng

import asyncio
from agentpay_vn import await_settlement

# Chờ tối đa 5 phút (300 giây) để khách thanh toán
async def wait_for_payment():
    try:
        settlement = await await_settlement(
            payment_id=payment.id,
            timeout_seconds=300
        )

        if settlement.status == "confirmed":
            print(f"✅ Thanh toán thành công! Số tiền: {settlement.amount} VNĐ")
            print(f"Mã giao dịch ngân hàng: {settlement.transaction_id}")
            # Ở đây: cấp quyền truy cập khóa học cho khách
            grant_course_access(customer_id=payment.customer_phone)
            return True
        else:
            print(f"❌ Thanh toán thất bại: {settlement.status}")
            return False

    except TimeoutError:
        print("⏱️ Hết thời gian chờ (5 phút)")
        return False

# Chạy hàm async
result = asyncio.run(wait_for_payment())

Giải thích từng phần: - await_settlement() lắng nghe bank feed (kết nối trực tiếp với ngân hàng) - Khi ngân hàng xác nhận tiền vào tài khoản → status == "confirmed" - transaction_id: Mã xác nhận từ ngân hàng (dùng để kiểm tra) - Nếu 5 phút mà khách chưa thanh toán → TimeoutError

Ví Dụ Thực Tế: Bot Bán Khóa Học Online

Hãy tưởng tượng bạn chạy một cửa hàng khóa học. Dưới đây là toàn bộ luồng:

from agentpay_vn import PaymentRequest, await_settlement
import asyncio

class CourseBot:
    def __init__(self):
        self.courses = {
            "python-beginner": {"name": "Python từ 0 đến 1", "price": 299000},
            "web-advanced": {"name": "Web Dev Nâng Cao", "price": 599000}
        }

    async def sell_course(self, course_id: str, customer_name: str, customer_phone: str):
        # Bước 1: Tạo payment request
        course = self.courses.get(course_id)
        if not course:
            return "❌ Khóa học không tồn tại"

        payment = PaymentRequest(
            amount=course["price"],
            description=course["name"],
            reference_id=f"course_{course_id}_{customer_phone}",
            customer_name=customer_name,
            customer_phone=customer_phone
        )

        # Bước 2: Gửi checkout
        checkout_url = payment.generate_checkout_url()
        qr_code = payment.generate_qr_code()

        message = f"""
        Bạn sắp mua: {course['name']}
        Giá: {course['price']:,} VNĐ

        Vui lòng quét mã QR hoặc vào: {checkout_url}
        """
        print(message)

        # Bước 3: Chờ thanh toán
        settlement = await await_settlement(payment.id, timeout_seconds=300)

        if settlement.status == "confirmed":
            # Cấp quyền truy cập
            self.grant_access(customer_phone, course_id)
            return f"✅ Chúc mừng! Bạn đã mua {course['name']} thành công. Truy cập tại đây: https://courses.vn/my/{course_id}"
        else:
            return "❌ Thanh toán thất bại. Vui lòng thử lại."

    def grant_access(self, phone: str, course_id: str):
        # Lưu vào database
        print(f"✅ Đã cấp quyền cho {phone} truy cập {course_id}")

# Sử dụng
bot = CourseBot()
result = asyncio.run(
    bot.sell_course(
        course_id="python-beginner",
        customer_name="Nguyễn Văn B",
        customer_phone="0909123456"
    )
)
print(result)

Kịch bản này giải quyết: 1. Khách hàng yêu cầu mua khóa học 2. Bot tạo mã QR với giá chính xác 3. Khách thanh toán qua ứng dụng ngân hàng 4. Ngân hàng xác nhận → Bot tự động cấp quyền 5. Khách nhận email đăng nhập vào khóa học

Nên & Không Nên Khi Dùng AgentPay VN

Nên Làm ✅ Không Nên ❌
Lưu reference_id để tracking đơn hàng Để timeout quá ngắn (<30 giây)
Xác nhận transaction_id từ ngân hàng Gửi QR code qua email không an toàn
Cài đặt webhook để xử lý settlement tự động Giữ tiền trong tài khoản trung gian
Ghi log mọi lỗi thanh toán Bỏ qua customer_phone (dùng để refund)
Test trên môi trường staging trước Để agent tự động phê duyệt mà không log

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

1. Tiền sẽ vào tài khoản của tôi bao lâu?

Trả lời: Thường trong vòng 1-3 phút sau khi khách thanh toán. Thời gian chính xác phụ thuộc vào ngân hàng của bạn. Techcombank thường nhanh nhất (~30 giây).

2. Có phí nào không? AgentPay có lấy hoa hồng?

Trả lời: Không. AgentPay VN là dự án open-source (MIT License). Bạn chỉ trả phí cho ngân hàng (thường 0.1-0.5% cho thanh toán QR), không có chi phí thêm từ AgentPay.

3. Nếu khách hàng phàn nàn "thanh toán mà không nhận được khóa học" thì sao?

Trả lời: Hãy kiểm tra:

# Xem lịch sử giao dịch
from agentpay_vn import get_payment_history
history = get_payment_history(days=7)
for h in history:
    print(f"{h.reference_id}: {h.amount} VNĐ - {h.status}")

Nếu status == "confirmed" nhưng khách không nhận quyền truy cập → Bug trong hệ thống của bạn, không phải lỗi AgentPay.

4. Có thể hoàn tiền được không?

Trả lời: Có thể, nhưng phức tạp hơn. Bạn cần: - Gửi yêu cầu hoàn tiền đến ngân hàng (thường qua app hoặc customer service) - AgentPay không xử lý hoàn tiền, vì tiền đã vào tài khoản của bạn

Tip: Lưu customer_phone để dễ xử lý hoàn tiền sau.

Cấu Hình Nâng Cao: Webhook & Logging

Nếu bạn muốn agent tự động xử lý mà không cần chờ (fire-and-forget), hãy dùng webhook:

from agentpay_vn import PaymentRequest, setup_webhook

# Cấu hình webhook
setup_webhook(
    url="https://yoursite.vn/webhooks/payment",
    events=["settlement_confirmed", "settlement_failed"]
)

# Handler endpoint (Flask example)
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/payment", methods=["POST"])
def handle_payment_webhook():
    data = request.json

    if data["event"] == "settlement_confirmed":
        reference_id = data["reference_id"]
        amount = data["amount"]

        # Cấp quyền truy cập
        course_id = reference_id.split("_")[1]
        customer_phone = reference_id.split("_")[2]
        grant_course_access(customer_phone, course_id)

        print(f"✅ Cấp quyền cho {customer_phone}")

    return {"status": "ok"}, 200

Tóm Tắt Nhanh

Bắt Đầu Ngay

Cài đặt SDK:

pip install agentpay-vn

Xem tài liệu đầy đủ tại: https://agentpay.servicesai.vn/v1/docs

Repo GitHub: https://github.com/phuocdu/agentpay-vn

Thử nghiệm đơn giản nhất:

from agentpay_vn import PaymentRequest
p = PaymentRequest(amount=100000, description="Test")
print(p.generate_checkout_url())  # Sẵn sàng!

Hãy biến Claude của bạn thành một "nhân viên bán hàng" thực thụ, có khả năng thu tiền ngay trong hội thoại. Đó là tương lai của AI commerce. 🚀

Bắt đầu →

← Tất cả bài