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

2026-09-04 · AgentPay VN

aipythonvietqrmcpthanh-toán

Bạn có một AI agent tuyệt vời, nhưng nó không thể nhận tiền

Hãy tưởng tượng: bạn vừa xây dựng một bot AI bán khoá học online. Nó trả lời câu hỏi học sinh, gợi ý bài tập phù hợp, thậm chí giáo dục cá nhân hóa. Tất cả hoạt động hoàn hảo... cho đến khi học sinh muốn thanh toán. Lúc đó bạn vẫn phải:

Dừng cuộc trò chuyện AI
Yêu cầu khách hàng sang trang thanh toán riêng
Quay lại để tiếp tục, hoặc tạo tài khoản mới
Lo lắng về việc bot sẽ không xác nhận được khoản thanh toán

Mất rồi. Trải nghiệm bị gián đoạn. Khách hàng có thể bỏ ngang.

Nếu bạn đang có cảm giác này, AgentPay VN sẽ giúp bạn giải quyết nó chỉ trong 10 phút.

Vấn đề thực tế: Tại sao thêm thanh toán lại khó?

Hầu hết các giải pháp thanh toán hiện nay được thiết kế cho website hoặc ứng dụng di động—những giao diện có form, button, callback. Nhưng AI agent lại khác:

Agent chạy trong hội thoại (chat, voice, hoặc automation)
Agent cần gọi công cụ (tool/function) một cách tự nhiên, không phải điều hướng người dùng
Hầu hết API thanh toán yêu cầu bạn "giữ" tiền (lưu trữ, quản lý), tạo thêm pháp lý và bảo mật
Tích hợp mất thời gian: setup database, webhook handler, retry logic...

Kết quả: 80% các agent AI được xây dựng với Claude, GPT, hoặc Anthropic không bao giờ có khả năng thanh toán.

Giới thiệu AgentPay VN: Thanh toán cho agent chỉ bằng 3 dòng code

AgentPay VN là một Python SDK mã nguồn mở (MIT license) + MCP server cho phép AI agent của bạn:

Tạo yêu cầu thanh toán → agent gửi URL checkout
Khách hàng scan QR → thanh toán trực tiếp vào tài khoản ngân hàng của bạn
Agent xác nhận → tự động tiếp tục logic kế tiếp

Quan trọng nhất: AgentPay không bao giờ giữ tiền. QR code trỏ thẳng tới tài khoản ngân hàng của bạn. Bank feed gửi về xác nhận, SDK chỉ cần chờ.

Agent AI ─── gọi create_payment_request() ──→ Nhận URL QR
              ↓
           Gửi checkout_url cho khách
              ↓
           Khách scan QR ──→ Thanh toán qua ngân hàng
              ↓
        await_settlement() nhận xác nhận
              ↓
           Agent tiếp tục logic (giao hàng, unlock khoá học...)

Hướng dẫn từng bước: Cài đặt trong 5 phút

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

Mở terminal và chạy:

pip install agentpay-vn

Tất cả xong. Không cần setup database, không cần chứng chỉ SSL, không cần tạo merchant account phức tạp.

Bước 2: Khởi tạo SDK trong code của bạn

from agentpay_vn import AgentPayClient, PaymentRequest

# Khởi tạo client với cấu hình đơn giản
client = AgentPayClient(
    merchant_account="your_bank_account@bank",  # VietQR format
    merchant_name="Your Shop Name",             # Tên hiển thị trên QR
    api_key="your_agentpay_api_key"             # Lấy từ dashboard
)

Giải thích: - merchant_account: Tài khoản ngân hàng của bạn (định dạng VietQR, ví dụ: 123456789@vietcombank) - merchant_name: Tên shop hiển thị khi khách hàng scan QR - api_key: Token để xác thực với AgentPay backend (lấy miễn phí từ dashboard)

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

Như đã nói, chỉ cần 3 bước. Dưới đây là code thực tế mà agent sẽ gọi:

# Step 1: Agent tạo yêu cầu thanh toán
payment_request = client.create_payment_request(
    amount_vnd=299000,                          # Số tiền: 299k VND
    description="Khoá học Python Advanced",    # Mô tả (hiển thị trên QR)
    customer_id="student_12345",                # ID khách (để tracking)
    timeout_seconds=600                         # QR hết hiệu lực sau 10 phút
)

# Step 2: Lấy checkout URL để gửi cho khách
checkout_url = payment_request.checkout_url
print(f"Khách vui lòng thanh toán tại: {checkout_url}")

# Step 3: Chờ xác nhận từ bank
settlement = client.await_settlement(
    request_id=payment_request.request_id,
    timeout_seconds=600                        # Chờ tối đa 10 phút
)

if settlement.is_confirmed:
    print(f"✅ Thanh toán thành công! Số tiền: {settlement.amount_vnd} VND")
    print(f"   Người chuyển: {settlement.sender_account}")
    print(f"   Mã giao dịch: {settlement.transaction_id}")

    # Agent tiếp tục logic: ghi nhập học, gửi tài liệu, unlock content...
    deliver_course_materials(customer_id=payment_request.customer_id)
else:
    print("❌ Thanh toán chưa được xác nhận, vui lòng thử lại.")

Từng dòng chi tiết: - create_payment_request(): Tạo session thanh toán với số tiền, mô tả, và timeout - checkout_url: URL mà agent gửi cho khách (có thể là QR inline hoặc link Zalo Pay) - await_settlement(): Hàm non-blocking chờ xác nhận từ bank feed (không spam API) - settlement.is_confirmed: True nếu ngân hàng xác nhận thanh toán

Tích hợp với Claude / Anthropic (MCP Server)

Nếu bạn dùng Claude API với Model Context Protocol (MCP), agent của bạn có thể tự gọi thanh toán mà không cần lập trình từng bước.

Cấu hình MCP Server

Tạo file mcp-config.json:

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "AGENTPAY_API_KEY": "your_api_key_here",
        "MERCHANT_ACCOUNT": "123456789@vietcombank",
        "MERCHANT_NAME": "Your Shop"
      }
    }
  }
}

Cài MCP server:

pip install agentpay-mcp

Sau đó, Claude sẽ tự động có các tool: - create_payment_request – tạo yêu cầu thanh toán - check_settlement_status – kiểm tra trạng thái - cancel_payment_request – hủy nếu cần

Ví dụ hội thoại:

User: "Tôi muốn mua khoá học Python Advanced, giá 299k."

Claude Agent:
  → Gọi tool: create_payment_request(amount_vnd=299000, description="Python Advanced")
  → Nhận: checkout_url = "https://agentpay.servicesai.vn/pay/abc123"
  → Trả lời: "✅ Tuyệt vời! Bạn vui lòng scan QR hoặc click link này để thanh toán..."
  → Chờ backend thông báo (await_settlement)
  → Khi bank confirm: "🎉 Thanh toán thành công! Tài liệu khoá học đã gửi vào email."

Ví dụ kịch bản đời thực: Bot bán khoá học

Hãy xem một use case hoàn chỉnh:

from agentpay_vn import AgentPayClient
import anthropic

# Cấu hình
client = AgentPayClient(
    merchant_account="0123456789@vietcombank",
    merchant_name="AI Learning Hub",
    api_key="your_key"
)

clause_client = anthropic.Anthropic()

def handle_course_purchase(course_name, price_vnd, customer_email):
    """Xử lý mua khoá học qua AI agent"""

    # 1. Tạo yêu cầu thanh toán
    payment_req = client.create_payment_request(
        amount_vnd=price_vnd,
        description=f"Khoá học: {course_name}",
        customer_id=customer_email,
        timeout_seconds=900  # 15 phút
    )

    print(f"📲 Vui lòng thanh toán: {payment_req.checkout_url}")

    # 2. Agent chờ xác nhận (non-blocking, không tốn CPU)
    settlement = client.await_settlement(
        request_id=payment_req.request_id,
        timeout_seconds=900
    )

    # 3. Nếu thanh toán thành công
    if settlement.is_confirmed:
        print(f"✅ Nhận {settlement.amount_vnd} VND từ {settlement.sender_account}")
        print(f"📧 Gửi tài liệu tới {customer_email}")
        print(f"🔓 Unlock khoá học {course_name}")

        # Giả sử có hàm helper
        send_course_materials(customer_email, course_name)
        return True
    else:
        print("❌ Thanh toán hết hạn. Vui lòng thử lại.")
        return False

# Chạy
handle_course_purchase(
    course_name="Python Advanced",
    price_vnd=299000,
    customer_email="student@example.com"
)

Kịch bản này mô tả: 1. Bot gợi ý khoá học, khách hỏi giá 2. Agent tạo QR thanh toán ngay trong chat 3. Khách scan + chuyển khoản (từ ứng dụng ngân hàng yêu thích) 4. Agent nhận xác nhận trong 5-10 giây 5. Tài liệu được gửi tự động, unlock khoá học

Không cần redirect, không cần chờ, không cần email xác nhận thủ công.

Nên làm gì & Không nên làm gì

✅ Nên	❌ Không nên
Sử dụng `await_settlement()` để chờ async	Gọi `check_settlement_status()` liên tục (spam API)
Lưu `request_id` để tracking	Giả vờ thanh toán đã thành công trước khi bank confirm
Set timeout hợp lý (300-900 giây)	Để QR hết hiệu lực sau 24h (khách quên, agent vẫn chờ)
Sử dụng `merchant_account` định dạng chuẩn VietQR	Nhập sai tài khoản rồi tự hỏi tại sao tiền không vào
Ghi log `transaction_id` cho audit	Bỏ qua transaction_id, khó debug sau
Test với amount nhỏ trước (1000 VND)	Deploy thẳng lên production với logic chưa kiểm chứng

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

1. AgentPay có giữ lại tiền không? Phải chia lợi nhuận không?

Không. AgentPay không bao giờ chạm tiền của bạn. QR code trỏ thẳng tới tài khoản ngân hàng của bạn—tiền vào tài khoản, bạn kiểm soát 100%. AgentPay chỉ là "người câu kết" giữa agent và bank API. Không có phí ẩn, không có chia lợi nhuận, không có giữ tiền.

2. Bao lâu thì nhận được tiền sau khi khách thanh toán?

Tùy ngân hàng, thường 3-5 phút nếu cùng ngân hàng, 5-30 phút nếu khác ngân hàng. SDK của bạn nhận xác nhận qua bank feed API, không phải đợi T+1 hay batch processing.

3. Nếu khách cancel đơn hàng, có thể hoàn tiền không?

Có. Bạn gọi refund_transaction() với transaction_id từ settlement. Tiền quay lại tài khoản khách trong 1-3 giờ. AgentPay xử lý bên backend.

4. Cần phải tạo account, setup merchant gì không?

Không. Chỉ cần cung cấp: - Tài khoản ngân hàng (bất kỳ ngân hàng nào có hỗ trợ VietQR) - Email để nhận api_key (miễn phí từ dashboard agentpay.servicesai.vn)

Đó là tất cả. Không form dài, không giấy tờ, không audit 3 ngày.

Tóm tắt nhanh

Cài đặt: pip install agentpay-vn (30 giây)
Viết code: 3 hàm chính: create_payment_request(), send checkout_url, await_settlement() (10 phút)
Không giữ tiền: Tiền thẳng vào tài khoản ngân hàng của bạn
Tích hợp AI dễ: Dùng MCP server để Claude/Anthropic tự gọi
Production-ready: Hỗ trợ retry, timeout, logging, QR inline
Mã nguồn mở: MIT license, review trên GitHub

Bước tiếp theo

Bạn đã sẵn sàng thêm thanh toán cho AI agent:

Đọc docs đầy đủ: https://agentpay.servicesai.vn/v1/docs
Clone example: https://github.com/phuocdu/agentpay-vn (folder examples/)
Cài và test ngay: pip install agentpay-vn → tạo .env → chạy python example.py
Lên production: Deploy MCP server, cấu hình Claude/GPT, kích hoạt agent

Các bot bán hàng, khoá học, dịch vụ AI sẽ không còn đơn giản chỉ "nói chuyện"—chúng sẽ bán, nhận tiền, giao hàng tất cả trong một cuộc hội thoại mượt mà.

Bắt đầu ngay. 10 phút là đủ.

Bắt đầu →

← Tất cả bài