Hướng dẫn kết nối

Hướng dẫn từng bước cài đặt và kết nối MCP Payment Server với Claude Desktop để thực hiện các thao tác thanh toán qua TCONNECT Payment API.

---

1. Cấu hình môi trường

Nội dung file .env:

# TCONNECT Payment API
PAYMENT_API_URL=https://api.tconnect.vn
PAYMENT_API_KEY=your_api_key_here
PAYMENT_PARTNER_ID=your_partner_id_here

# AES-256-CBC encryption key (hex, 64 chars)
AES_KEY=your_aes_key_here

important

Các giá trị PAYMENT_API_KEY, PAYMENT_PARTNER_ID, và AES_KEY được cấp bởi TCONNECT. Liên hệ TCONNECT để nhận thông tin xác thực.

---

2. Cài đặt với Docker (Khuyến nghị)

Bước 1 — Chuẩn bị thư mục

mkdir mcp-payment-server && cd mcp-payment-server
cp .env.example .env
# Cập nhật .env với API key thực tế

Bước 2 — Build và khởi động

docker-compose up --build

Kiểm tra:

docker-compose ps

---

3. Cài đặt không dùng Docker

python -m venv venv
source venv/bin/activate      # macOS / Linux
venv\Scripts\activate         # Windows

pip install -r requirements.txt
cp .env.example .env
python server.py

---

4. Kết nối với Claude Desktop

Đường dẫn file cấu hình

Hệ điều hành	Đường dẫn
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Cấu hình dùng Docker

{
  "mcpServers": {
    "payment": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/đường/dẫn/tới/mcp-payment-server/docker-compose.yml",
        "run", "--rm", "mcp-payment-server"
      ]
    }
  }
}

Cấu hình dùng Python trực tiếp

{
  "mcpServers": {
    "payment": {
      "command": "python",
      "args": ["/đường/dẫn/tới/mcp-payment-server/server.py"]
    }
  }
}

ghi chú

Khởi động lại Claude Desktop hoàn toàn sau khi cập nhật cấu hình. Biểu tượng MCP xuất hiện trong giao diện chat khi kết nối thành công.

---

5. Kiểm tra kết nối

Sau khi kết nối thành công, thử gõ câu lệnh sau trong Claude Desktop:

Lấy danh sách dịch vụ thanh toán

Claude sẽ gọi tool get_services tự động.

---

6. Ví dụ sử dụng

Câu lệnh	Tool được gọi	Ghi chú
"Tạo QR thanh toán 50,000 VND đơn hàng ORD001"	create_qr_payment	amount=50000, order_id=ORD001
"Đẩy thanh toán 100,000 VND tới thiết bị serial 00059012710"	push_payment_to_device	serial_no=00059012710, amount=100000
"Giao dịch QR ngày 07/01/2026"	get_qr_transactions	from_date=2026-01-07 00:00:00
"Tạo virtual account ngân hàng VCCB tên NGUYEN VAN A"	create_virtual_account	bank_code=970454, account_name=NGUYEN VAN A
"Giải mã IPN callback nhận được"	decrypt_ipn_payload	encrypted_data từ TCONNECT

important

MCP Payment Server thực hiện giao dịch tài chính thực. Luôn kiểm tra kỹ PAYMENT_API_URL trỏ đúng môi trường dev hoặc production trước khi sử dụng.