Thu tiền từ bot Telegram bằng VietQR và AgentPay

2026-08-19 · AgentPay VN

agentpayvietqrtelegrampythonai

Nỗi đau của những người bán hàng qua bot Telegram

Bạn là developer, hoặc quản lý cộng đồng bán khóa học, ebooks, khóa tư vấn qua Telegram. Mỗi lần có khách hàng mới, bạn phải yêu cầu họ chuyển tiền thủ công, sau đó tự tay kiểm tra hóa đơn, xác nhận thanh toán, rồi gửi tài liệu. Tốn thời gian, dễ sai sót, khách hàng bực dọc vì chậm. Còn nếu dùng Stripe hoặc PayPal, phí cao (2-3%), quá trình xét duyệt lâu, không phù hợp với thị trường Việt.

Bạn cần một cách: nhanh, rẻ, an toàn, không cần trung gian giữ tiền. Đó chính là AgentPay VN – giải pháp mã mở dựa trên VietQR mà chúng ta sẽ khám phá hôm nay.

AgentPay VN là gì? Tại sao nó khác biệt?

AgentPay VN là một Python SDK mã mở (MIT) cho phép các AI agent (hoặc bot thường) tạo yêu cầu thanh toán VietQR, gửi QR code cho khách hàng, và tự động xác nhận khi tiền về. Đặc biệt quan trọng:

Cơ bản, quy trình chỉ 3 bước:

  1. create_payment_request → Tạo yêu cầu thanh toán
  2. send checkout_url → Gửi QR/URL cho khách
  3. await_settlement → Chờ tiền về, tự động xử lý tiếp

Cài đặt và khởi tạo AgentPay VN

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

pip install agentpay-vn

Rất đơn giản. Sau đó, import vào project:

from agentpay_vn import AgentPayClient, PaymentRequest

# Khởi tạo client (cần API key từ dashboard AgentPay)
client = AgentPayClient(api_key="your_api_key_here")

Bước 2: Cấu hình thông tin tài khoản ngân hàng

Bạn cần liên kết tài khoản ngân hàng Việt (hỗ trợ các ngân hàng có chuẩn VietQR như Vietcombank, Techcombank, Agribank, v.v.). Quy trình:

  1. Truy cập https://agentpay.servicesai.vn/v1/docs
  2. Đăng ký tài khoản, xác thực ngân hàng (thường qua OTP)
  3. Lấy API key từ dashboard
  4. Lưu vào file .env (KHÔNG commit vào git)
# .env
AGENTPAY_API_KEY=sk_live_xxxxx
MERCHANT_ACCOUNT=123456789  # Số tài khoản
MERCHANT_BANK=Vietcombank

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv("AGENTPAY_API_KEY")
client = AgentPayClient(api_key=api_key)

Ví dụ thực tế: Bot bán khóa học qua Telegram

Giả sử bạn có một bot Telegram bán khóa "Python cho AI" giá 299.000 VND. Dưới đây là flow đầu đủ:

Bước 1: Tạo yêu cầu thanh toán

from agentpay_vn import AgentPayClient, PaymentRequest
import os

client = AgentPayClient(api_key=os.getenv("AGENTPAY_API_KEY"))

# Tạo payment request
payment_request = client.create_payment_request(
    amount=299000,  # VND
    description="Khóa học: Python cho AI - Lớp 2024",
    customer_email="khach@example.com",
    customer_phone="0912345678",
    metadata={
        "course_id": "python_ai_2024",
        "user_telegram_id": 123456789,
        "user_name": "Nguyễn Văn A"
    },
    callback_url="https://your-bot-api.com/payment-callback"
)

print(f"Payment ID: {payment_request.id}")
print(f"QR Code URL: {payment_request.qr_code_url}")
print(f"Checkout URL: {payment_request.checkout_url}")

Giải thích từng dòng: - amount=299000: Số tiền khách phải trả (đơn vị VND) - description: Mô tả hiển thị trên QR code - metadata: Dữ liệu tùy ý lưu trữ, dùng để khi tiền về, bot biết khách nào, gửi tài liệu cho ai - callback_url: Endpoint bot sẽ nhận webhook khi tiền về

Bước 2: Gửi QR code cho khách qua Telegram

import requests
from telegram import Bot

# Khởi tạo Telegram bot
TG_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")
bot = Bot(token=TG_TOKEN)

chat_id = 123456789  # Chat ID của khách hàng

# Gửi QR code (dạng hình ảnh)
bot.send_photo(
    chat_id=chat_id,
    photo=payment_request.qr_code_url,
    caption=f"""Quét mã QR để thanh toán:
    💰 Số tiền: 299.000 VND
    📚 Khóa học: Python cho AI
    ⏰ Hiệu lực: 30 phút

    Hoặc click vào link checkout: {payment_request.checkout_url}
    """
)

# Lưu payment_request.id vào database để xử lý callback sau
db.save_payment_order(
    payment_id=payment_request.id,
    telegram_user_id=chat_id,
    course_id="python_ai_2024",
    status="pending"
)

Bước 3: Xử lý webhook khi tiền về

# Sử dụng Flask (ví dụ)
from flask import Flask, request
from agentpay_vn import verify_webhook_signature

app = Flask(__name__)

@app.route("/payment-callback", methods=["POST"])
def payment_callback():
    """
    AgentPay gửi webhook khi tiền đã đến tài khoản
    """
    data = request.json
    signature = request.headers.get("X-AgentPay-Signature")

    # Xác thực chữ ký (bảo mật)
    if not verify_webhook_signature(data, signature, os.getenv("AGENTPAY_WEBHOOK_SECRET")):
        return {"error": "Invalid signature"}, 401

    payment_id = data["payment_id"]
    status = data["status"]  # "settled", "failed", etc.
    amount_received = data["amount"]

    if status == "settled":
        # Tiền đã về tài khoản
        order = db.get_payment_order(payment_id)
        telegram_user_id = order["telegram_user_id"]
        course_id = order["course_id"]

        # Gửi tài liệu khóa học cho khách
        bot.send_message(
            chat_id=telegram_user_id,
            text="✅ Thanh toán thành công! Khóa học đang được tải..."
        )

        course_file = get_course_file(course_id)
        bot.send_document(
            chat_id=telegram_user_id,
            document=course_file,
            caption="📚 Tài liệu khóa học Python cho AI. Hãy bảo mật tài liệu này!"
        )

        # Cập nhật status
        db.update_payment_order(payment_id, status="delivered")

    elif status == "failed":
        # Thanh toán thất bại
        order = db.get_payment_order(payment_id)
        bot.send_message(
            chat_id=order["telegram_user_id"],
            text="❌ Thanh toán thất bại. Vui lòng thử lại."
        )

    return {"ok": True}, 200

Tích hợp MCP Server cho AI Agents

Nếu bạn muốn Claude hoặc các AI agents khác tự động xử lý thanh toán mà không cần code tùy chỉnh, hãy dùng MCP server:

Cài đặt MCP server

pip install agentpay-mcp

Cấu hình Claude Desktop (hoặc AI agent khác)

Tạo file claude_desktop_config.json (trên macOS: ~/.claude_desktop_config.json):

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp.server"],
      "env": {
        "AGENTPAY_API_KEY": "sk_live_xxxxx",
        "WEBHOOK_SECRET": "your_webhook_secret"
      }
    }
  }
}

Sau đó, Claude sẽ có thể gọi các tool AgentPay trực tiếp:

User: "Tôi muốn bán khóa học này giá 500k, giúp tôi tạo QR code thanh toán"

Claude: (sử dụng AgentPay MCP)
→ create_payment_request(amount=500000, description="...")
→ Tạo QR code
→ Trả về: "✅ QR code đã tạo, bạn có thể chia sẻ..."

So sánh AgentPay với các giải pháp khác

Tiêu chí AgentPay VN Stripe PayPal Chuyển khoản thủ công
Phí giao dịch 0% 2.9% + 5k 2% 0%
Xác nhận tự động ✅ ✅ ✅ ❌
Hỗ trợ VietQR ✅ ❌ ❌ ✅
Không lưu tiền ✅ ❌ ❌ ✅
Mã mở (MIT) ✅ ❌ ❌ N/A
Tích hợp AI/MCP ✅ ❌ ❌ ❌
Thời gian xét duyệt 1-2 ngày 3-5 ngày 7-14 ngày N/A
Phù hợp Việt Nam ✅ ⚠️ ⚠️ ✅

Những điều "nên" và "không nên" khi dùng AgentPay

✅ Nên làm:

❌ Không nên:

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

1. Tiền về tài khoản ngân hàng mất bao lâu?

Thường 1-2 giờ sau khi khách quét QR code thanh toán. Tuy nhiên, webhook AgentPay sẽ thông báo ngay (có thể mất vài phút do xác nhận ngân hàng). Nếu chưa nhận webhook sau 5 phút, bạn có thể poll API: client.get_payment_status(payment_id).

2. Nếu khách thanh toán số tiền sai sót thì sao?

AgentPay hỗ trợ kiểm tra số tiền tự động. Nếu khách chỉ chuyển 280k thay vì 299k, webhook sẽ có status="partial". Bạn có thể yêu cầu khách hoàn tất thanh toán hoặc coi như hoàn tất tùy logic business của bạn.

3. Có thể refund được không? Khách hối lộn mua nhầm?

AgentPay không xử lý refund trực tiếp (vì không lưu tiền). Bạn cần chuyển lại tiền từ tài khoản ngân hàng của bạn cho khách thủ công, hoặc thoả thuận khác. Ghi lại memo "Refund cho payment_id: xxx" để tracking.

4. AgentPay có bảo mật không? Liệu QR code có bị lộ?

Có. QR code tuy công khai, nhưng chỉ dùng cho một giao dịch cụ thể, số tiền được fix sẵn. Nếu ai đó share QR, chỉ khách thanh toán trước mới nhận được tài liệu. API key cần bảo mật như password (lưu .env, không share công khai).

Tóm tắt nhanh

Bước tiếp theo: Chạy thử ngay

Bạn đã hiểu cơ bản, bây giờ là lúc thực hành:

# 1. Cài AgentPay
pip install agentpay-vn

# 2. Đăng ký tài khoản & lấy API key
# Truy cập: https://agentpay.servicesai.vn/v1/docs

# 3. Clone ví dụ từ GitHub
git clone https://github.com/phuocdu/agentpay-vn
cd agentpay-vn/examples

# 4. Chạy ví dụ Telegram bot
python examples/telegram_bot_example.py

Nếu gặp vấn đề, tham khảo tài liệu chi tiết tại đây hoặc tạo issue trên GitHub repository.

Chúc bạn thành công trong hành trình số hóa thanh toán! 🚀

Bắt đầu →

← Tất cả bài