Tạo MCP Server Thu Phí: Để Claude Nhận Thanh Toán Trực Tiếp

2026-08-01 · AgentPay VN

mcp-serverai-agentpythonvietqragentpay

Nỗi Đau Thực Tế: Chatbot Của Bạn Không Thể Nhận Tiền

Hãy tưởng tượng: Khách hàng đang trò chuyện với bot bán khoá học của bạn trên Claude. Họ hỏi "Mình muốn mua khoá Premium, giá bao nhiêu?" — bot trả lời tận tình, nhưng khi đến bước thanh toán thì... gì xảy ra? Người dùng phải rời khỏi cuộc hội thoại, tìm trang thanh toán, điền thông tin, chờ xác nhận. Gián đoạn trải nghiệm. Mất đơn hàng.

Hoặc tệ hơn: bạn là một quán cà phê muốn bot AI ghi nhận đơn hàng trực tiếp từ khách, nhưng không có cách nào để xác minh họ đã thanh toán mà không rời app. Tin tưởng bị phá vỡ.

Vấn đề lõi: AI agent của bạn chỉ có thể nói chuyện, không thể hành động tài chính.

Cho đến bây giờ.

Giải Pháp: MCP Server + VietQR = Thanh Toán Ngay Trong Chat

AgentPay VN là một Python SDK mã nguồn mở (MIT) cho phép bạn xây dựng MCP server riêng — điểm kết nối giữa Claude và hệ thống thanh toán. Cách hoạt động:

Claude tạo yêu cầu thanh toán qua MCP server của bạn
Server phát sinh QR code VietQR (điểm trực tiếp đến tài khoản ngân hàng của bạn)
Khách quét, chuyển tiền (không qua trung gian)
Ngân hàng xác nhận, server phát hiện và thông báo cho Claude
Chat tiếp tục với xác nhận thanh toán hoàn toàn tự động

Điểm quan trọng: AgentPay không giữ tiền. Mỗi QR đều trỏ thẳng vào tài khoản merchant của bạn. Không có escrow, không có account ở giữa. Chỉ là một lớp kết nối thông minh.

Cài Đặt & Setup Ban Đầu

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

Mở terminal, chạy:

pip install agentpay-vn

SDK này cung cấp các hàm core: create_payment_request(), await_settlement(), và helpers khác. Kích thước nhỏ, phụ thuộc tối thiểu (chỉ requests, pydantic).

Bước 2: Tạo MCP Server

Tạo file agentpay_mcp_server.py:

from mcp.server import Server
from agentpay_vn import create_payment_request, await_settlement
import json

# Khởi tạo MCP server
server = Server("agentpay-mcp")

# Thiết lập thông tin merchant của bạn
MERCHANT_BANK_ACCOUNT = "0123456789"
MERCHANT_BANK_NAME = "MB"  # Techcombank, Vietcombank, etc.
MERCHANT_NAME = "Your Shop"

@server.call_tool()
async def handle_create_payment(amount: int, description: str, request_id: str) -> dict:
    """
    Tạo yêu cầu thanh toán VietQR.

    Args:
        amount: Số tiền (VND, không có dấu phẩy)
        description: Mô tả (ví dụ: "Khoá học Python - User123")
        request_id: ID duy nhất để theo dõi (ví dụ: UUID)

    Returns:
        dict chứa qr_url, qr_code_base64, settlement_timeout
    """
    try:
        # Gọi SDK để tạo payment request
        payment = create_payment_request(
            merchant_account=MERCHANT_BANK_ACCOUNT,
            merchant_bank=MERCHANT_BANK_NAME,
            merchant_name=MERCHANT_NAME,
            amount=amount,
            description=description,
            request_id=request_id,
            timeout_seconds=300  # QR hợp lệ 5 phút
        )

        return {
            "status": "success",
            "qr_url": payment["qr_url"],
            "qr_code_base64": payment["qr_code_base64"],  # Hiển thị trong chat
            "request_id": request_id,
            "amount": amount,
            "expires_at": payment["expires_at"]
        }
    except Exception as e:
        return {
            "status": "error",
            "message": str(e)
        }

@server.call_tool()
async def handle_await_settlement(request_id: str, timeout: int = 60) -> dict:
    """
    Chờ xác nhận thanh toán từ ngân hàng.

    Args:
        request_id: ID của payment request tạo trước đó
        timeout: Số giây tối đa chờ (mặc định 60s)

    Returns:
        dict chứa settlement status, transaction_id, timestamp
    """
    try:
        # SDK kết nối với bank feed, polling cho xác nhận
        settlement = await_settlement(
            request_id=request_id,
            timeout_seconds=timeout
        )

        return {
            "status": "settled",
            "request_id": request_id,
            "transaction_id": settlement["transaction_id"],
            "amount": settlement["amount"],
            "settled_at": settlement["settled_at"],
            "payer_name": settlement.get("payer_name", "Unknown")
        }
    except TimeoutError:
        return {
            "status": "timeout",
            "request_id": request_id,
            "message": "Chưa nhận thanh toán trong thời gian quy định"
        }
    except Exception as e:
        return {
            "status": "error",
            "message": str(e)
        }

if __name__ == "__main__":
    server.run()

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

@server.call_tool(): Định nghĩa một tool mà Claude có thể gọi. MCP sẽ expose nó qua JSON-RPC.
create_payment_request(): Hàm SDK chính. Nhận thông tin merchant + số tiền, trả về QR code (URL hoặc base64).
await_settlement(): Hàm polling. Nó kết nối với bank feed (qua API ngân hàng hoặc webhook) và chờ ghi nhận chuyển khoản khớp với request_id.
timeout_seconds=300: QR hợp lệ 5 phút. Sau đó tự hết hiệu lực (tính năng bảo mật).

Bước 3: Cấu Hình MCP Cho Claude

Tạo/chỉnh sửa file ~/.claude_desktop_config.json (hoặc config của bạn):

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["/path/to/agentpay_mcp_server.py"],
      "env": {
        "MERCHANT_BANK_ACCOUNT": "0123456789",
        "MERCHANT_BANK_NAME": "MB",
        "MERCHANT_NAME": "Your Shop"
      }
    }
  }
}

Sau khi khởi động, Claude sẽ thấy hai tool: handle_create_payment và handle_await_settlement.

Kịch Bản Thực Tế: Bot Bán Khoá Học Online

Giả sử bạn chạy một bot hỗ trợ bán khoá Python:

Hội thoại thực tế:

User: "Mình muốn mua khoá Python Advanced, giá bao nhiêu?"

Claude: "Khoá Python Advanced giá 599,000 VND, bao gồm:
- 20 video bài học
- Source code 50+ project
- Support 6 tháng

Bạn muốn mua không?"

User: "Có, mình mua"

[Claude gọi create_payment_request tool]

Claude: "Tuyệt vời! Đây là mã QR thanh toán:

[QR code hiển thị]

Quét mã bằng app ngân hàng hoặc VietQR, chuyển 599,000 VND. Mình sẽ xác nhận ngay khi nhận được tiền."

User: [Quét QR, chuyển tiền qua ngân hàng]

[Claude gọi await_settlement tool, polling...]

[Sau 3-5 giây, bank feed xác nhận]

Claude: "✓ Thanh toán thành công! Tôi đã nhận 599,000 VND lúc 14:32.

Khoá học của bạn đã được kích hoạt. Đăng nhập vào trang học tập với email của bạn để bắt đầu.

Câu hỏi tiếp theo về khoá học?"

Trong backend của bạn:

request_id = UUID của transaction
Sau khi await_settlement() trả về success, bạn cập nhật DB: UPDATE users SET course_purchased = TRUE WHERE user_id = 'User123' AND course_id = 'python-adv'
Tạo token truy cập khoá học, gửi email

Trải nghiệm liền mạch. Không phải rời khỏi chat.

Luồng 3 Bước Cốt Lõi

1. Create Payment Request

# Gọi từ Claude thông qua MCP
payment = create_payment_request(
    merchant_account="0123456789",
    merchant_bank="MB",
    merchant_name="Python Academy",
    amount=599000,
    description="Khoá Python Advanced - User@example.com",
    request_id="uuid-1234-5678",
    timeout_seconds=300
)

print(payment["qr_url"])  # https://qr.vietcombank.vn/...
print(payment["qr_code_base64"])  # Base64 để hiển thị inline

2. Send Checkout URL (hoặc QR trực tiếp)

Claude hiển thị: - QR code (base64 hoặc URL ảnh) - Text: "Quét QR hoặc bấm liên kết để chuyển tiền" - Deadline: "Có hiệu lực trong 5 phút"

3. Await Settlement

# Gọi từ Claude sau khi gửi QR
settlement = await_settlement(
    request_id="uuid-1234-5678",
    timeout_seconds=60  # Chờ tối đa 60 giây
)

if settlement["status"] == "settled":
    print(f"✓ Thanh toán xác nhận: {settlement['transaction_id']}")
    # Cập nhật DB, gửi tài nguyên, v.v.
else:
    print("Chưa nhận thanh toán")

Tính Năng Nâng Cao

Webhook thay vì Polling

Thay vì chờ với await_settlement(), bạn có thể đăng ký webhook với ngân hàng. Khi có giao dịch khớp, ngân hàng gọi callback URL của bạn. SDK hỗ trợ webhook handler:

from agentpay_vn import create_webhook_handler

handler = create_webhook_handler(
    on_settlement=lambda req_id, txn: {
        # Gửi sự kiện về Claude thông qua MCP
        print(f"Thanh toán {req_id} xác nhận!")
    },
    secret_key="your_webhook_secret"
)

# Expose qua FastAPI, Flask, v.v.
app.post("/webhook/settlement")(handler)

Ghi Nhật Ký & Monitoring

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("agentpay_mcp")

logger.info(f"Payment created: {request_id}, amount: {amount}")
logger.info(f"Settlement confirmed: {transaction_id}")

Xử Lý Lỗi Graceful

try:
    settlement = await_settlement(request_id, timeout=60)
except TimeoutError:
    # QR hết hạn, gợi ý user tạo lại
    return {"status": "retry", "message": "QR hết hiệu lực, vui lòng tạo lại"}
except ConnectionError:
    # Mất kết nối bank feed
    return {"status": "pending", "message": "Kiểm tra kết nối, thử lại sau"}

Nên Làm & Không Nên Làm

✓ Nên Làm	✗ Không Nên Làm
Set `timeout_seconds` hợp lý (300-600s)	Để QR hợp lệ quá lâu (>1h)
Lưu trữ `request_id` + `user_id` trong DB	Giả mạo payment hoàn toàn trong code
Validate amount > 0 trước gọi SDK	Gửi QR mà không có description rõ
Ghi log tất cả transactions	Bỏ qua error từ `await_settlement()`
Test với amount nhỏ trước (ví dụ 1,000 VND)	Relay QR code của user khác
Dùng HTTPS cho MCP server	Lưu merchant account trong code plain text

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

Q1: AgentPay có giữ tiền không?

Không. Mỗi QR code trỏ trực tiếp vào tài khoản merchant của bạn (VietQR là tiêu chuẩn của các ngân hàng Việt). AgentPay chỉ là SDK để tạo & theo dõi request. Tiền đi thẳng vào bank account của bạn, không qua trung gian.

Q2: Nếu customer không quét QR trong 5 phút thì sao?

QR hết hiệu lực. Bạn gợi ý Claude tạo QR mới. SDK sẽ trả về timeout error từ await_settlement(), Claude có thể đề nghị user thử lại với QR mới. Không bị phí gì.

Q3: Mất kết nối ngân hàng, thanh toán không xác nhận được?

SDK có retry logic & exponential backoff. Nếu bank feed offline, await_settlement() sẽ timeout thay vì crash. Bạn có thể: - Yêu cầu user chờ & thử lại - Cấu hình webhook để ngân hàng callback sau khi online trở lại - Kiểm tra tài khoản thủ công để xác nhận giao dịch muộn

Q4: Có cách nào để refund không?

Refund là trách nhiệm của bạn (chuyển tiền ngược). AgentPay SDK sẽ release tính năng create_refund_request() trong v2 (đang phát triển). Hiện tại, refund thủ công qua ngân hàng hoặc bot của bạn có thể gợi ý user liên hệ hỗ trợ.

Tóm Tắt Nhanh

Cài đặt: pip install agentpay-vn
MCP Server: Xây dựng với @server.call_tool() expose create_payment_request & await_settlement
Cấu hình Claude: Thêm MCP server vào .claude_desktop_config.json
Luồng: Create → Send QR → Await Settlement → Confirm
An toàn: Không giữ tiền, QR tự hết hiệu lực, log/validate tất cả
Sử dụng: Chatbot bán khóa, đặt hàng, membership, donation, v.v.

Bước Tiếp Theo

Cài đặt SDK: pip install agentpay-vn
Đọc docs đầy đủ: https://agentpay.servicesai.vn/v1/docs
Fork repo & test: https://github.com/phuocdu/agentpay-vn
Xây dựng MCP server riêng theo hướng dẫn trên
Kết nối Claude và thử hội thoại thanh toán đầu tiên

Cho Claude khả năng nhận tiền là bước ngoặt. Bạn không chỉ có chatbot — bạn có một tác nhân AI kinh doanh hoàn toàn tự động, 24/7, không lỗi, không cần con người can thiệp vào quá trình bán hàng.

Bắt đầu ngay hôm nay. 🚀

Bắt đầu →

← Tất cả bài