Danh sách tool SePay MCP

Danh sách tool SePay MCP mà ứng dụng AI gọi được, kèm nhóm quyền cần cấp, câu hỏi mẫu và tham số cho giao dịch, doanh thu, tài khoản, hạn mức, webhook, cổng thanh toán, hóa đơn điện tử.

||

Bạn hỏi bằng lời thường, ứng dụng AI tự chọn tool và tham số của SePay MCP để trả lời. Khi ứng dụng AI báo không đọc được một loại dữ liệu, tìm tool ứng với câu hỏi trong các bảng để biết cần bật nhóm quyền nào.

Trang này là bản tóm tắt. Lập trình viên cần schema đầy đủ (kiểu dữ liệu, mô tả từng tham số) thì gọi tools/list tới https://my.sepay.vn/mcp, không cần đăng nhập.

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.

SePay MCP có đúng một thao tác ghi: gửi lại webhook, chỉ chạy khi bạn cấp nhóm quyền Gửi lại webhook (có xác nhận) và bấm Duyệt trên my.sepay.vn cho từng lần gửi. Các tool còn lại không thay đổi dữ liệu. Không tool nào trả về số dư tài khoản. Webhook đã cấu hình được trả về không kèm khóa bí mật.

Ví dụ: doanh thu tháng này so tháng trước

Ngày 31/10, bạn hỏi: "Doanh thu tháng này so với tháng trước thế nào, tính theo mã thanh toán?"

Ứng dụng AI gọi get_cashflow_report một lần cho cả 2 tháng, chia theo tháng, chỉ tính giao dịch có mã thanh toán:

Tham số AI truyền:

JSON
1
2
3
4
5
6
{
"period": "month",
"basis": "with_code",
"from_date": "2026-09-01",
"to_date": "2026-10-31"
}

Kết quả (rút gọn, số liệu mẫu):

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
"report": {
"basis": "with_code",
"period": "month",
"from_date": "2026-09-01",
"to_date": "2026-10-31",
"total_in": 182500000,
"count_in": 412,
"by_bank_account": [
{
"bank_account": { "xid": "ba_7Kq2", "bank_name": "VietinBank", "account_number": "****6789", "label": "Tài khoản bán hàng" },
"in": 176300000
}
],
"gateway_in": 6200000,
"gateway_count": 9,
"timeline": [
{ "period": "2026-09", "in": 95000000 },
{ "period": "2026-10", "in": 87500000 }
],
"includes_gateway": true,
"notes": ["Tiền cổng thanh toán chuyển về tài khoản đã liên kết khác (nếu có) đã nằm trong số tiền của tài khoản đó, có thể trùng với phần thanh toán qua cổng."]
},
"hidden_fields": ["bank_account.account_number"]
}

Từ timeline, ứng dụng AI trả lời: tháng 9 thu 95.000.000 đ, tháng 10 thu 87.500.000 đ, thấp hơn 7.500.000 đ (khoảng 7,9%). basis là cách tính doanh thu: with_code chỉ cộng giao dịch có mã thanh toán, kể cả tiền vào qua cổng thanh toán bằng thẻ và NAPAS (gateway_in); all_in cộng mọi tiền vào và tiền ra (dòng tiền, có cả chuyển quỹ nội bộ); via_va chỉ cộng tiền vào qua tài khoản ảo.

Quyền cần có để dùng tool

Tool tài liệu (list_docs, fetch_content) dùng được ngay sau khi thêm SePay vào ứng dụng AI, không cần đăng nhập SePay.

Các tool còn lại đọc dữ liệu của công ty bạn. Để dùng, bạn phải cấp quyền khi kết nối và bật nhóm quyền của tool đó. Tài khoản Người dùng bình thường còn cần quyền xem tính năng tương ứng trên SePay; thiếu quyền này thì tool không hiện trong ứng dụng AI. Bảng nhóm quyền và quyền tính năng ở Quyền và bảo mật SePay MCP.

Tool đối soát hóa đơn get_einvoice_reconciliation cần cả 2 nhóm quyền Xem hóa đơn điện tử và Xem giao dịch.

Tool tài liệu SePay

ToolNhóm quyềnCâu hỏi mẫu
list_docsKhông cần"Tài liệu SePay có những nhóm nào?"
fetch_contentKhông cần"Hướng dẫn tích hợp webhook SePay chi tiết thế nào?"

Ứng dụng AI thường gọi list_docs để tìm trang, rồi gọi fetch_content để đọc nội dung trang trên developer.sepay.vn.

Tool giao dịch

ToolNhóm quyềnCâu hỏi mẫu
list_transactionsXem giao dịch"Liệt kê 10 giao dịch tiền vào hôm nay." / "Đơn hàng DH00012 đã được thanh toán chưa?"
get_transaction_summaryXem giao dịch"Tháng này khách Nguyễn Văn A chuyển mấy lần, tổng bao nhiêu?"
get_transactionXem giao dịch"Xem chi tiết giao dịch thứ hai trong danh sách vừa rồi."
get_cashflow_reportXem giao dịch"Doanh thu tháng này so với tháng trước thế nào?" / "Chốt ca sáng hôm qua của điểm bán Quầy 1."

payment_code là mã đơn người chuyển khoản ghi trong nội dung, ví dụ DH00012. Khi bạn hỏi về một đơn hàng, ứng dụng AI lọc giao dịch theo mã này. payment_status là paid khi giao dịch có mã thanh toán và xác thực tự động thành công, unpaid khi có mã thanh toán nhưng xác thực tự động chưa thành công, no_code khi chuyển khoản không ghi mã thanh toán. Nội dung, mã tham chiếu và giao dịch tiền ra bị ẩn nếu bạn bật tùy chọn ẩn khi cấp quyền.

Mỗi tool một việc: list_transactions chỉ trả danh sách, không có tổng. Số giao dịch và tổng tiền của đúng một bộ lọc ("khách A chuyển mấy lần, tổng bao nhiêu") lấy từ get_transaction_summary. Doanh thu, dòng tiền theo kỳ, theo điểm bán, theo ca chỉ lấy từ get_cashflow_report; get_transaction_summary không dùng để tính doanh thu.

Tool tài khoản ngân hàng và VA

ToolNhóm quyềnCâu hỏi mẫu
list_bank_accountsXem tài khoản ngân hàng"Tôi đang kết nối những tài khoản ngân hàng nào?"
get_bank_accountXem tài khoản ngân hàng"Tài khoản ACB của tôi còn kết nối không?"
list_virtual_accountsXem tài khoản ảo (VA)"Liệt kê các tài khoản ảo của tài khoản BIDV."

Bật Ẩn số tài khoản khi cấp quyền thì số tài khoản chỉ còn 4 số cuối.

Tool hạn mức gói

ToolNhóm quyềnCâu hỏi mẫu
get_plan_quotaXem hạn mức gói"Gói dịch vụ của tôi còn lại bao nhiêu hạn mức?" / "Tôi còn bao nhiêu lượt xuất hóa đơn điện tử?"

get_plan_quota trả hạn mức của gói SePay (lượt giao dịch: chu kỳ đang tính lượt, số lượt đã dùng, giới hạn, lượt còn lại) và hóa đơn điện tử (lượt xuất: số hóa đơn đã phát hành từ trước tới nay, lượt còn lại; không có chu kỳ). Chỉ tài khoản SuperAdmin và Admin dùng được tool này. Với Người dùng bình thường, ứng dụng AI không thấy tool hạn mức gói.

Tool webhook

ToolNhóm quyềnCâu hỏi mẫu
list_webhook_logsXem lịch sử webhooks"Có webhook nào gửi thất bại trong tuần này không?"
get_webhook_reportXem lịch sử webhooks"Tỉ lệ webhook gửi lỗi tháng này là bao nhiêu?"
list_webhooksXem webhooks đã cấu hình"Tôi đang cấu hình những webhook nào?"
get_webhookXem webhooks đã cấu hình"Webhook này gửi tới URL nào, xác thực kiểu gì?"

list_webhook_logs trả về sự kiện, trạng thái, mã HTTP, thời gian và giao dịch của mỗi lần gửi, nên trả lời được câu "giao dịch nào bị lỗi webhook gần đây". Log không có URL nhận webhook. Muốn biết webhook gửi tới đâu, ứng dụng AI gọi thêm list_webhooks hoặc get_webhook; URL ở hai tool này chỉ còn tên miền, ví dụ https://abc.example.com/…, phần đường dẫn và tham số phía sau bị ẩn.

Gửi lại webhook (thao tác ghi)

ToolNhóm quyềnCâu hỏi mẫu
replay_webhookGửi lại webhook (có xác nhận)"Gửi lại webhook bị lỗi của đơn DH00012."

replay_webhook gửi lại một lần gửi webhook bị lỗi, chỉ sau khi bạn bấm Duyệt trên my.sepay.vn. Quyền cần có, cách duyệt và kết quả trả về ở Gửi lại webhook qua SePay MCP.

Tool cổng thanh toán

ToolNhóm quyềnCâu hỏi mẫu
list_pg_ordersXem đơn cổng thanh toán"Tuần này cổng thanh toán có bao nhiêu đơn đã thanh toán, tổng bao nhiêu?"
get_pg_orderXem đơn cổng thanh toán"Đơn DH1001 trên cổng thanh toán đã thu tiền chưa, có hoàn tiền không?"

list_pg_orders là số liệu đơn hàng của cổng (đơn đã tạo, đã thanh toán, đã hủy). Doanh thu chung của công ty, kể cả tiền vào qua cổng, lấy từ get_cashflow_report; ứng dụng AI không cộng 2 con số này với nhau. Số thẻ chỉ còn 4 số cuối, không có tên chủ thẻ.

Tool hóa đơn điện tử

ToolNhóm quyềnCâu hỏi mẫu
list_einvoicesXem hóa đơn điện tử"Tháng này tôi đã xuất bao nhiêu hóa đơn, tổng tiền bao nhiêu?"
get_einvoiceXem hóa đơn điện tử"Hóa đơn DH1001 có bị điều chỉnh hay thay thế không?"
get_einvoice_reconciliationXem hóa đơn điện tử và Xem giao dịch"Tháng 10 có khoản nào đã thu tiền mà chưa xuất hóa đơn?"

Tổng tiền của list_einvoices không cộng trùng hóa đơn gốc với hóa đơn thay thế nó. get_einvoice trả cả chuỗi hóa đơn gốc, thay thế, điều chỉnh liên quan. Kết quả của get_einvoice_reconciliation là gợi ý để bạn xác nhận. Một cách ghép khoản tiền với hóa đơn chắc chắn là theo reference_code, nên đặt reference_code theo quy ước mã tham chiếu. Lượt xuất hóa đơn còn lại xem bằng get_plan_quota.

Tiếp theo