SePay CLI

SePay CLI: công cụ dòng lệnh để bạn và AI tích hợp thanh toán SePay

Với SePay CLI, bạn làm tích hợp SePay ngay trong terminal, từ lúc chạy thử trên sandbox đến khi cấu hình và đối soát trên production. Tự gõ lệnh, hoặc để AI lập trình gõ giúp.

Dùng được với

  • Logo Claude CodeClaude Code
  • Logo CodexCodex
  • Logo CursorCursor
  • Logo Gemini CLIGemini CLI
~/shop-api · sandbox

$sepay sandbox init --with-webhook-listen --yes

Created bank account 832529c1-… (ACB).

Created listen-only webhook 5f0e2a7b-….

$sepay webhook listen --forward localhost:3000

✓ Listening for sandbox events → http://localhost:3000/

# Terminal thứ hai: khách chuyển thiếu 5.000 đ cho đơn 50.000 đ

$sepay sandbox simulate payment_in --bank-account <ba_xid> --amount 45000 --code DH1709

Simulated payment_in event.

14:22:07 payment_in → http://localhost:3000/ 200 12ms txn=a41c9e02-… wh=5f0e2a7b-…

# Log của ứng dụng bạn:

handler: DH1709 nhận 45.000 / 50.000 đ → đánh dấu “thanh toán thiếu”

Thử các tình huống thanh toán trước khi lên production

Tạo giao dịch giả trên sandbox bất cứ lúc nào, không cần nhờ ai chuyển khoản.

Nhận webhook ngay trên máy dev

Đẩy webhook về localhost, không cần địa chỉ công khai hay công cụ mở cổng.

$ sepay webhook listen --forward localhost:3000 --print

Giả lập khách chuyển khoản

Tạo giao dịch giả trên sandbox, kể cả tình huống tiền về thiếu hoặc thừa so với đơn.

$ sepay sandbox simulate payment_in --bank-account <ba_xid> --amount 45000 --code DH1709

Người đọc được, AI cũng đọc được

Bảng để bạn xem, thêm --json để AI đọc. --help của mỗi lệnh có phần hướng dẫn cho AI.

$ sepay transaction list --json

Kiểm thử webhook trong CI

Gửi giao dịch thử vào code nhận webhook và kiểm tra kết quả mỗi lần build.

$ sepay webhook test --forward localhost:3000 --amount 50000 --expect-status 200

Chạy thử lệnh SePay CLI ngay trên trang

Chọn nhóm lệnh rồi bấm Chạy thử.

Đọc tài liệu đầy đủ
  • Đủ cả quy trình tích hợpSandbox, mã thanh toán, webhook, đối soát, cổng thanh toán, hóa đơn. Có cả lệnh cho Bank Hub.
  • Làm sẵn cho AICó --map=json, sepay help và hướng dẫn riêng cho AI.
  • An toànMặc định chạy sandbox. Trên production phải ghi rõ --env production.
$sepay --map=json
{
  "name": "sepay",
  "version": "x.x.x",
  "active_env": "sandbox",
  "authenticated": true,
  "active_profile": "dev@congty.vn",
  "commands": [ /* … */ ]
}

# Mỗi --help có khối hướng dẫn cho agent

$sepay webhook delete --help
[Agent guidance]
  Active env: sandbox (no real money).
  Irreversible: there is no command that undoes this. Confirm the target before running it.
  Prompts in sandbox too; there, without a terminal it exits 2 until you pass --yes.
  …

# Bảng mã thoát để script và AI biết xử lý tiếp thế nào, có sẵn trong CLI

$sepay help exit-codes
# Exit codes
| 0 | Success | |
| 2 | Bad flags, bad arguments, unknown command, or a production write that needs the user's confirmation | … |
| 4 | Not logged in | `sepay login` |
| 5 | The token lacks the required scope | `sepay login --scopes <scope>` |
…

Lệnh và kết quả lấy từ tài liệu SePay CLI (đã rút gọn).

Không lo sửa nhầm dữ liệu thật

  • Mặc định chạy sandboxGiao dịch giả chỉ nằm trên sandbox. Muốn đổi mặc định sang production, CLI hỏi lại trước khi lưu.
  • Trên production thì phải ghi rõLệnh thay đổi dữ liệu phải ghi rõ --env production, thiếu thì CLI không chạy trên production.
  • Đúng quyền của tài khoảnCLI chỉ làm được những gì tài khoản đăng nhập được phép, và trong phạm vi (scope) bạn cấp lúc đăng nhập.
  • Lệnh không hoàn tác được: AI không tự chạy hàng loạtAI chỉ chạy tiếp bằng --yes khi lệnh nêu đúng mã của một tài nguyên; còn lại CLI dừng và nhờ bạn tự gõ lệnh. Chạy trên terminal thì CLI hỏi lại, mặc định là Không.
Xác nhận trên production

$sepay webhook update 5f0e2a7b-… --name "Webhook don hang" --env production

! live: update webhook targets PRODUCTION

? update webhook on production? [y/N]

# Gõ y để chạy. Không có terminal để trả lời thì lệnh dừng với exit code 2.

Cài SePay CLI

Cài CLI, đăng nhập bằng tài khoản SePay đang có, rồi tạo sandbox. Cần tài khoản SuperAdmin, Admin hoặc có quyền Developer.

  1. Cài đặtChọn hệ điều hành ở khung cài đặt.
  2. Đăng nhậpsepay login mở trang Kết nối thiết bị trên my.sepay.vn, nhập mã mà CLI hiện ra.
  3. Tạo sandboxsepay sandbox init --with-webhook-listen --yes

Chạy trong terminal, không cần sudo:

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

Hướng dẫn đầy đủ

Dùng SePay CLI cùng Skills và MCP

Mỗi công cụ lo một việc, từ lúc viết code đến khi bán hàng.

  1. 1. SePay Skills: viết codeAI viết code nhận thanh toán đúng ngay từ đầu.Xem SePay Skills →
  2. 2. SePay CLI: chạy thử và vận hànhCLI để chạy thử trên sandbox, cấu hình và đối soát trên production. Kiểm thử trong CI.
  3. 3. SePay MCP: theo dõiKhi đã bán hàng, hỏi AI về giao dịch và webhook. Người dùng thường cần SuperAdmin hoặc Admin bật quyền “Cho phép kết nối AI qua MCP”.Xem SePay MCP →

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

Không thấy câu bạn cần? Liên hệ SePay.

CLI là gì?

CLI (Command-line interface) là công cụ chạy bằng lệnh gõ chữ, không có giao diện bấm nút. Lập trình viên và AI lập trình dùng CLI vì nhanh, dễ tự động hóa; bạn không rành kỹ thuật thì để AI chạy giúp. Nên cho AI dùng một profile đăng nhập riêng.

SePay CLI có sửa nhầm dữ liệu thật không?

Mặc định là không. CLI chạy trên sandbox, giao dịch giả chỉ nằm ở đó. Muốn làm trên production, lệnh phải ghi rõ --env production. AI chỉ chạy tiếp bằng --yes khi lệnh nêu đúng mã của một tài nguyên; còn lại CLI dừng và nhờ bạn tự gõ lệnh.

AI dùng CLI thế nào?

AI đọc sepay --map=json để biết có lệnh nào, tra sepay help khi cần. Với lệnh thay đổi dữ liệu trên production, AI chỉ chạy tiếp bằng --yes khi lệnh nêu đúng mã của một tài nguyên; còn lại CLI dừng và nhờ bạn tự gõ lệnh.

Đăng nhập CLI thế nào?

Chạy sepay login. CLI in ra một mã thiết bị và mở trang Kết nối thiết bị trên my.sepay.vn để bạn nhập mã. Không cần dán mật khẩu vào terminal.

Có chạy trong CI được không?

Được. Dùng sepay webhook test --forward localhost:3000 --amount 50000 --expect-status 200 để kiểm tra handler trả đúng mã phản hồi trong mỗi lần build.

SePay CLI khác SePay MCP thế nào?

CLI để bạn hoặc AI chạy lệnh tích hợp, đọc và sửa được dữ liệu trong phạm vi được cấp. MCP để hỏi số liệu ngay trong ứng dụng AI. 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.

Chạy thử tích hợp SePay ngay trong terminal

Cài SePay CLI, tạo sandbox, rồi tự gõ lệnh hoặc để AI chạy giúp. Cần AI viết code thì dùng thêm SePay Skills.