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 --printSePay CLI
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
$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”
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.
Đẩ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 --printTạ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 DH1709Bả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 --jsonGử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 200Chọn nhóm lệnh rồi bấm Chạy thử.
--map=json, sepay help và hướng dẫn riêng cho AI.--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>` | …
sepay login# Mở trang Kết nối thiết bị trên my.sepay.vn, nhập mã thiết bị CLI in ra
sepay sandbox init --with-webhook-listen --yesCreated bank account 832529c1-8a40-11f1-b996-fa163e2f7c98 (ACB). Created listen-only webhook 5f0e2a7b-9c11-11f1-b996-fa163e2f7c98. 832529c1-8a40-11f1-b996-fa163e2f7c98
sepay paycode create DH --character-type NumberOnly --suffix-from 4 --suffix-to 10 --active✓ Created pay code structure DH.
# Xem cấu trúc mã thanh toán hiện tại
sepay paycode listsepay webhook listen --forward localhost:3000 --print✓ Listening for sandbox events → http://localhost:3000/ (Ctrl+C to stop · retries+enter to manage)
# Terminal thứ hai: tạo giao dịch giả trên sandbox
sepay sandbox simulate payment_in --bank-account <ba_xid> --amount 50000 --code DH1709Simulated payment_in event. a41c9e02-9c12-11f1-b996-fa163e2f7c98
# Terminal đang listen in ra
14:22:07 payment_in → http://localhost:3000/ 200 12ms txn=a41c9e02-… wh=5f0e2a7b-…
sepay webhook test --forward localhost:3000 --amount 50000 --expect-status 200Fired payment_in event; waiting for the handler... ✓ handler responded 200 in 12ms
sepay pg checkout init --amount 50000 --description "Thanh toan don HD1709" --invoice HD1709# Trang thanh toán sandbox tự mở trên trình duyệt
sepay pg order get HD1709sepay einvoice invoice create @hoa-don.json✓ submitted (tracking 084e179d-2c1a-4f5e-9b7d-3a6f1e2d8c40) poll: sepay einvoice invoice create-status 084e179d-2c1a-4f5e-9b7d-3a6f1e2d8c40
sepay transaction list --webhook-success 0 --transaction-date-from 2026-09-22ID DATE AMOUNT CONTENT CODE BANK WH b7d30f15-9c12-11f1-b996-fa163e2f7c98 2026-09-22 15:40:12 +120.000 DH1712 thanh toan don hang DH1712 ACB fail page 1/1 · 1 of 1
Lệnh và kết quả lấy từ tài liệu SePay CLI (đã rút gọn).
--env production, thiếu thì CLI không chạy trên production.--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.$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 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.
sepay login mở trang Kết nối thiết bị trên my.sepay.vn, nhập mã mà CLI hiện ra.sepay sandbox init --with-webhook-listen --yesChạy trong terminal, không cần sudo:
$ curl -fsSL https://get.sepay.vn/sepay-cli-install.sh | shChạy trong PowerShell hoặc Command Prompt, không cần quyền admin:
> powershell -c "irm https://get.sepay.vn/sepay-cli-install.ps1 | iex"Mở cửa sổ terminal mới để dùng lệnh sepay. Dùng Scoop thì xem hướng dẫn đầy đủ.
Mỗi công cụ lo một việc, từ lúc viết code đến khi bán hàng.
Không thấy câu bạn cần? Liên hệ SePay.
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.
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 đọ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.
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. 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.
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.
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.