Bắt đầu nhanh: SePay Skills, MCP và CLI cho AI agent

Bắt đầu với SePay Skills, MCP và CLI: ChatGPT, Claude hướng dẫn tích hợp, AI tra giao dịch qua MCP, CLI thử webhook ngay trên máy.

||

SePay có các công cụ cho AI agent:

  • SePay Skills để ChatGPT, Claude hướng dẫn bạn tích hợp đúng, và agent lập trình viết code tích hợp.
  • SePay MCP để ứng dụng AI đọc dữ liệu trong tài khoản SePay của bạn.
  • SePay CLI để nhận webhook ngay trên máy, tương tác với dữ liệu sandbox và production qua dòng lệnh.

Mỗi công cụ cài riêng và chạy độc lập, không công cụ nào cần công cụ khác. Bạn có thể chọn một hoặc kết hợp nhiều công cụ với nhau theo nhu cầu sử dụng.

Cài SePay Skills để AI hướng dẫn tích hợp

SePay Skills giúp AI trả lời đúng theo tài liệu SePay về webhook, VietQR, cổng thanh toán, SePay API, từ cách bật trên my.sepay.vn tới code tích hợp. Cài không cần tài khoản SePay.

Trong ChatGPT, Claude

Tải tệp skill

Tệp luôn là bản mới nhất từ repo chính thức sepayvn/sepay-skills. Giữ nguyên tệp zip, không giải nén.

Thêm vào ứng dụng

Với Claude: chọn ảnh đại diện ở góc dưới bên trái → Cài đặt (Settings) → Skills → Thêm (Add) → Tải Skill lên (Upload skill), chọn sepay.zip. Claude bật skill ngay sau khi tải lên. Bạn cũng mở thẳng được trang Skills của Claude.

Trang Cài đặt của Claude, mở menu Thêm ở mục Skills để tải skill lên
Nhấn để phóng to
Cài đặt → Skills → Thêm → Tải Skill lên, rồi chọn sepay.zip.

ChatGPT, Gemini, Grok xem ở Cài SePay Skills vào ứng dụng chat AI.

Hỏi thử

Mở cuộc trò chuyện mới và hỏi: "tôi muốn tích hợp xác thực thanh toán tự động cho cửa hàng online của tôi". Claude hiện Loaded skill sepay khi dùng skill.

Trong agent lập trình

Cần một agent hỗ trợ skill như Claude Code, Codex, Cursor.

Cài skill

Chọn tab theo agent bạn dùng:

Chạy trong terminal, không cần mở Claude Code trước, không cần Node.js:

$ claude plugin install sepay --marketplace sepayvn/sepay-skills

Hoặc gõ lệnh sau ngay trong Claude Code, kết quả như lệnh trên:

Claude Code
> /plugin install sepay --marketplace sepayvn/sepay-skills

Các lệnh tải skill từ repo sepayvn/sepay-skills trên GitHub; bạn có thể mở repo xem nội dung skill trước khi cài.

Mở phiên mới của agent

Agent đọc danh sách skill lúc khởi động, nên phiên đang mở chưa thấy skill vừa cài.

Hỏi thử

Nhờ agent: "Tích hợp SePay webhook bằng PHP để xác nhận đơn hàng khi khách chuyển khoản." Claude Code hiện dòng Skill(sepay) kèm Successfully loaded skill khi nạp skill.

Claude Code nạp skill sepay sau câu hỏi tích hợp SePay webhook bằng PHP
Nhấn để phóng to
Agent nạp skill sepay khi bạn nhờ việc liên quan tới SePay.

Bạn có thể tra thư mục cài theo từng agent, cách cập nhật và gỡ skill, hoặc những việc skill giúp được.

Kết nối SePay MCP để hỏi dữ liệu tài khoản

Hỏi ứng dụng AI bằng câu thường và nhận câu trả lời lấy từ chính tài khoản SePay của bạn: giao dịch, báo cáo dòng tiền, đơn hàng đã thanh toán chưa, webhook gửi lỗi, hạn mức gói. SePay MCP: Mặc định chỉ đọc. Thao tác ghi chỉ chạy khi bạn cấp quyền và xác nhận từng lần. Câu hỏi về tài liệu tích hợp SePay trả lời được ngay, không cần đăng nhập.

Cần có:

  • Tài khoản SePay đang hoạt động tại my.sepay.vn.
  • Người dùng phụ cần được chủ tài khoản hoặc quản trị viên cấp quyền dùng AI Agent.
  • Một ứng dụng AI hỗ trợ MCP, ví dụ Claude, ChatGPT, Claude Code, Codex, Cursor.

Mở AI Agent

Trên my.sepay.vn, ở nhóm Tích hợp & Thông báo, mở AI Agent, chọn Tạo kết nối rồi chọn thẻ của ứng dụng AI bạn dùng.

Trang Tạo kết nối trên my.sepay.vn, cột Bạn dùng ứng dụng AI nào? có 7 thẻ Claude, Claude chế độ Code, Claude Code, ChatGPT, Codex, Cursor, Khác
Nhấn để phóng to
Trang Tạo kết nối, thẻ Claude đang được chọn.

Làm theo các bước trên thẻ

Mỗi thẻ có các bước đánh số dành riêng cho ứng dụng đó: mở mục nào trong ứng dụng, dán giá trị nào vào ô nào, bấm nút gì. Làm lần lượt từng bước. Địa chỉ máy chủ, Client ID hay lệnh kết nối đều có nút sao chép ngay trên thẻ, dùng nút đó thay vì gõ tay.

Ví dụ thẻ Claude (claude.ai và ứng dụng Claude cho máy tính) có bốn bước:

  1. Chọn ảnh đại diện ở góc dưới bên trái → Cài đặt (Settings) → Trình kết nối (Connectors), chọn Thêm (Add) rồi chọn Thêm trình kết nối tùy chỉnh (Add custom connector).
  2. Đặt tên tùy ý, ví dụ SePay, dán địa chỉ https://my.sepay.vn/mcp vào ô thứ hai rồi bấm Tiếp tục (Continue).
  3. Ở Xác thực (Authentication) chọn Đăng nhập ngay (Sign in now). Ở Ứng dụng khách OAuth (OAuth client) chọn Dùng ứng dụng khách OAuth của riêng bạn (Use your own OAuth client), dán Client ID trên thẻ và để trống ô Mã bí mật ứng dụng khách OAuth (OAuth client secret).
  4. Bấm Thêm (Add), sau đó bấm Kết nối (Connect).

Với Claude Code và Codex, thẻ cho sẵn lệnh để bạn sao chép và chạy trong terminal. Với Cursor, chọn thẻ Khác rồi làm theo Kết nối Cursor với SePay qua MCP.

Đăng nhập và cấp quyền

Trình duyệt mở trang đăng nhập SePay khi bạn bấm Kết nối (Connect), chạy lệnh đăng nhập hoặc lần đầu hỏi về dữ liệu, tùy ứng dụng. Đăng nhập, bật các nhóm dữ liệu muốn chia sẻ rồi chọn Đồng ý cấp quyền. Trên cùng màn hình, bạn ẩn được giao dịch tiền ra, nội dung giao dịch, mã tham chiếu và số tài khoản. Những lần sau không phải đăng nhập lại.

Màn hình cấp quyền của SePay: bật tắt các nhóm quyền, nhóm Thao tác ghi tắt sẵn và danh sách việc AI không được phép
Nhấn để phóng to
Mỗi nhóm quyền bật tắt riêng. Mặc định chỉ đọc. Thao tác ghi chỉ chạy khi bạn cấp quyền và xác nhận từng lần. AI không xem số dư.

Hỏi thử

Quay lại ứng dụng AI và hỏi, ví dụ: "Vẽ biểu đồ lịch sử giao dịch năm 2026, có dashboard tổng tiền và tỉ trọng tiền vào, tiền ra." Ứng dụng AI gọi tool của SePay MCP để lấy giao dịch rồi trả lời.

Claude dựng dashboard dòng tiền năm 2026 từ dữ liệu SePay: tổng tiền vào, tiền ra, tỉ trọng và tiền vào theo từng tài khoản
Nhấn để phóng to
Claude lấy giao dịch qua SePay MCP và dựng dashboard dòng tiền.

Bạn đổi hoặc thu hồi quyền lúc nào cũng được trên trang AI Agent. Hướng dẫn từng bước cho từng ứng dụng:

Bạn cũng tra được tool nào trả lời câu hỏi nào và cần cấp quyền gì.

Cài SePay CLI để thử webhook trên máy

Lệnh sepay chuyển webhook sandbox tới code trên máy bạn mà không cần URL công khai, giả lập giao dịch để thử code, và tra cứu, quản lý giao dịch, webhook, mã thanh toán trên production khi thêm --env production. Kết quả xuất được dạng JSON, nên agent đọc được.

Cần có:

  • Máy macOS, Linux hoặc Windows (x64 hoặc arm64).
  • Tài khoản my.sepay.vn có vai trò SuperAdmin, Admin hoặc được cấp quyền Developer. CLI chỉ chạy với các vai trò này, trên cả sandbox lẫn production.

Cài CLI

Chọn tab theo hệ điều hành, rồi chọn một cách cài:

Homebrew:

$ brew install sepayvn/sepay-cli/sepay

Script cài một dòng, không cần Homebrew:

$ curl -fsSL https://get.sepay.vn/sepay-cli-install.sh | sh

npm, khi đã có Node.js 18 trở lên:

$ npm install -g sepay-cli

Cài bằng go install, cài vào một dự án và cách cập nhật, gỡ ở Cài đặt SePay CLI.

Kiểm tra bản đã cài:

$ sepay versionsepay version x.x.x (xxxxxxx, YYYY-MM-DD)https://github.com/sepayvn/sepay-cli/releases/tag/vx.x.x

sepay version in ra số phiên bản là đã cài xong.

Đăng nhập

$ sepay loginOpen your browser to authenticate. Your code: XXXX-XXXXOpening https://my.sepay.vn/...✓ Logged in as dev@congty.vnadd another account with: sepay login --profile <name>

CLI in một mã trên terminal và mở trang Kết nối thiết bị trên my.sepay.vn. Nhập mã đó rồi bấm Tiếp tục, terminal báo Logged in as kèm email tài khoản của bạn.

Trang Kết nối thiết bị trên my.sepay.vn: ô Mã thiết bị và nút Tiếp tục
Nhấn để phóng to
Nhập mã CLI in ra vào ô Mã thiết bị rồi bấm Tiếp tục.

Tạo dữ liệu sandbox

$ sepay sandbox init --with-webhook-listen --yesCreated bank account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98 (ACB).Created listen-only webhook 5f0e2a7b-xxxx-xxxx-xxxx-fa163e2f7c98.832529c1-xxxx-xxxx-xxxx-fa163e2f7c98

Lệnh tạo một tài khoản ngân hàng sandbox và một webhook chỉ để lắng nghe. Dòng cuối là xid của tài khoản ngân hàng, bước sau sẽ cần. Quên thì xem lại bằng sepay bank-account list.

Nhận webhook đầu tiên

Chạy code nhận webhook của bạn ở localhost:3000. Terminal 1 nhận webhook sandbox và chuyển tới code đó. Terminal 2 giả lập một giao dịch tiền vào 50.000 đ có mã đơn DH1709 trên tài khoản ở bước trước:

Terminal 1: nhận webhook
$ sepay webhook listen --forward localhost:3000env: sandbox  Delivering for every bank account of this company.✓ Listening for sandbox events → http://localhost:3000/   (Ctrl+C to stop · retries+enter to manage)14:22:07  payment_in   → http://localhost:3000/   200   12ms   txn=a41c9e02-xxxx-xxxx-xxxx-fa163e2f7c98   wh=5f0e2a7b-xxxx-xxxx-xxxx-3c9d81e04b6a
Terminal 2: giả lập giao dịch
$ sepay sandbox simulate payment_in --bank-account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98 --amount 50000 --code DH1709env: sandboxSimulated payment_in event.a41c9e02-xxxx-xxxx-xxxx-fa163e2f7c98

Terminal 1 in một dòng cho webhook vừa gửi: 200 là mã HTTP code của bạn trả về, txn= là xid của giao dịch vừa tạo.

Chưa có code nhận webhook thì nhờ agent đã cài SePay Skills dựng handler theo ngôn ngữ bạn dùng, hoặc dùng handler mẫu PHP, Node.js. Bạn cũng có thể cài CLI vào dự án, cập nhật hoặc gỡ CLI.

Mọi lệnh sửa dữ liệu trên production chỉ chạy khi bạn tự xác nhận trên terminal của mình. AI không tự xác nhận thay bạn: gặp lệnh này, AI đưa lệnh để bạn tự chạy. Những việc agent cần làm khi dùng CLI có trong quy ước SePay CLI cho AI agent.

Tiếp theo