Trên production, SePay CLI chỉ xem đơn: pg order list và pg order get (Xem đơn trên production). Các lệnh pg khác chỉ chạy trên sandbox, với dữ liệu giả lập; trên production, dùng API Cổng thanh toán hoặc my.sepay.vn.
Thử handler IPN của Cổng thanh toán trên sandbox trước khi lên production bằng nhóm lệnh pg của SePay CLI. Các lệnh này tạo đơn và chuyển IPN của đơn đó về handler trên máy bạn. Khái niệm và luồng thanh toán xem ở Giới thiệu, Luồng thanh toán và IPN.
Bạn cần đăng nhập và công ty đã bật Test mode. pg ipn set, pg order cancel và pg order void chỉ chạy trên sandbox và hỏi xác nhận; không có terminal thì thêm --yes.
Thứ tự lệnh khi thử một đơn:
pg ipn set → pg ipn listen → pg checkout init → (khách trả) → pg order get
sepay webhook listenkhông nhận thông báo của đơn Cổng thanh toán; nhóm này dùngpg ipn listen.- Lệnh
pg ordernhận số hóa đơn (order_invoice_number) đặt lúc tạo đơn, ví dụHD1709, không nhận xid. Trong terminal, bỏ trống số hóa đơn thì CLI cho chọn đơn từ danh sách; trong script, thiếu số hóa đơn là lỗi exit code 2.
pg auth và pg merchant get
CLI tự lấy credential sandbox khi cần và không in secret. Kiểm tra credential đã sẵn sàng chưa:
$ sepay pg authenv: sandboxPRODUCT ENV AUTH MERCHANTpg sandbox basic DEV-SEPAY-DEMO--refresh lấy bộ credential mới; --insecure-storage lưu credential trong tệp 0600 thay vì keychain.
Xem phương thức thanh toán của merchant và phương thức nào đang bật:
$ sepay pg merchant getenv: sandboxPAYMENT METHOD ACTIVECARD yesBANK_TRANSFER yesNAPAS_BANK_TRANSFER yespg ipn set
Đặt IPN URL trước khi tạo đơn: chưa có URL thì SePay không gửi IPN, và pg ipn listen không có bản nào để sao lại.
Tham số
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
<url> | string | Có | URL http hoặc https công khai, truy cập được từ Internet; SePay từ chối localhost và địa chỉ nội bộ |
--secret | string | Không | Chuỗi tự đặt, SePay gửi trong header X-Secret-Key; - đọc từ stdin. Có --secret thì xác thực tự bật |
--active | bool | Không | --active bật, --active=false tắt việc gửi IPN |
--auth-type | string | Không | SECRET_KEY, hoặc để trống để tắt xác thực |
--content-type | string | Không | Kiểu nội dung của request IPN: application/json |
Lệnh chỉ đổi giá trị bạn truyền; flag bỏ trống giữ giá trị đang lưu, nên đặt lại URL không tắt xác thực. Trong terminal, khi không có --secret và --auth-type, CLI hỏi giữ secret cũ, nhập secret mới (gõ ẩn) hay tắt xác thực. Nếu CLI không đọc được cấu hình đang lưu, lệnh không hỏi mà giữ nguyên xác thực cũ và in could not read the current config; keeping the stored auth (pass --secret or --auth-type to change it); muốn đổi thì truyền --secret hoặc --auth-type.
Ví dụ
Đặt địa chỉ nhận IPN kèm secret:
$ sepay pg ipn set https://example.com/sepay/ipn --secret <secret>Xem cấu hình IPN đang lưu:
$ sepay pg ipn getenv: sandboxURL: https://example.com/sepay/ipnAuth: SECRET_KEYContent: application/jsonSecret: ****1234Active: yesMỗi merchant có một cấu hình IPN. Sau khi đặt, secret chỉ hiện dạng đã che, không đọc lại được.
pg ipn listen
Chuyển tiếp bản sao IPN tới handler trên máy bạn. Lệnh không mở cổng trên máy: SePay vẫn gửi IPN tới IPN URL, CLI đẩy thêm một bản sao vào handler.
Tham số
| Flag | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
--forward | string | Trong script | Địa chỉ handler. Trong terminal, bỏ trống thì CLI hỏi |
--print | bool | Không | In toàn bộ payload |
--events | string[] | Không | Chỉ chuyển các loại ORDER_PAID, TRANSACTION_VOID |
--order | string | Không | Chỉ chuyển IPN của đơn có mã đơn này (order_id, ví dụ PAY36AE748559932D), không phải số hóa đơn |
Flag khác: sepay pg ipn listen --help.
Ví dụ
$ sepay pg ipn listen --forward localhost:3000/ipn✓ Listening for sandbox gateway IPN → http://localhost:3000/ipn (Ctrl+C to stop · retries+enter to manage)14:31:52 ORDER_PAID → http://localhost:3000/ipn 200 38ms order=HD1709order= là số hóa đơn, dùng thẳng với pg order get. Cấu trúc IPN và xác thực: IPN Cổng thanh toán.
Ghi chú
- Bản sao mang đúng body và header mà IPN URL vừa nhận, nên handler chạy cả bước kiểm tra
X-Secret-Key. Header này chỉ được chuyển khi handler nằm trên máy bạn (localhost); địa chỉ khác không nhận header này, trừ khi thêm--forward-credentials. --headersin header của request, giá trị thông tin xác thực nhưX-Secret-Keyđược che.- Lệnh chỉ sao lần gửi đầu tiên của SePay, không sao các lần SePay gửi lại.
- Khi chuyển tới handler gặp lỗi kết nối hoặc hết thời gian chờ, CLI gửi lại theo lịch gửi lại của SePay (
--forward-retries, mặc định7, tối đa10;0là một lần). CLI chỉ gửi lại khi handler nằm trên máy bạn. Dừnglistenthì các lần gửi lại đang chờ bị bỏ. Chi tiết: webhook listen. - Handler trả 4xx hoặc 5xx vẫn tính là đã nhận và không được gửi lại, khác với
webhook listen.
pg checkout init
Tạo đơn và in URL trang thanh toán. Trong terminal, URL tự mở trên trình duyệt.
Tham số
| Flag | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
--amount | string | Có | Số tiền VND, số nguyên: lớn hơn 0 với PURCHASE, bằng 0 với VERIFY |
--description | string | Có | Mô tả đơn |
--invoice | string | Với PURCHASE | Số hóa đơn: chữ không dấu, số, -, _; tối đa 100 ký tự |
--operation | string | Không | PURCHASE (mặc định) | VERIFY |
--payment-method | string | Không | BANK_TRANSFER | CARD | NAPAS_BANK_TRANSFER, phải đang bật trên merchant. Bỏ trống thì khách chọn cách trả trên trang thanh toán |
--success-url, --cancel-url, --error-url | string | Không | URL khách được đưa về khi trả xong, tự hủy, gặp lỗi. Có scheme như https://, không khoảng trắng hay ký tự điều khiển, tối đa 2048 ký tự; javascript:, data:, vbscript:, file:, blob:, about: bị chặn. Ghi http://localhost:3000/done, không ghi localhost:3000/done |
--currency | string | Không | Chỉ nhận VND (mặc định) |
--customer | string | Không | ID khách hàng |
--no-open | bool | Không | Chỉ in URL, không mở trình duyệt |
Sai định dạng số tiền, --invoice hoặc URL thì CLI dừng trước khi tạo đơn và in giá trị bị từ chối. Dữ liệu thanh toán thử: Sandbox Cổng thanh toán.
Ví dụ
Tạo đơn HD1709 50.000 VND, kèm ba URL đưa khách về trang đơn hàng:
$ sepay pg checkout init --amount 50000 --description "Thanh toan don HD1709" --invoice HD1709 --success-url "https://example.com/order/HD1709?payment=success" --cancel-url "https://example.com/order/HD1709?payment=cancel" --error-url "https://example.com/order/HD1709?payment=error"Lệnh in URL trang thanh toán ra stdout và mở trang đó trên trình duyệt:

pg order get và pg order list
Xem một đơn theo số hóa đơn:
$ sepay pg order get INV_20261101_801env: sandboxInvoice: INV_20261101_801Order ID: PAY36AE748559932DStatus: CAPTUREDAmount: 50000.00 VNDOrder ID là mã đơn mà pg ipn listen --order nhận. Khi kết quả của SePay có giao dịch của đơn, lệnh in thêm bảng giao dịch, số thẻ đã che. Mô tả đơn chỉ có trong --json.
Liệt kê đơn đã thanh toán trong khoảng ngày:
$ sepay pg order list --status CAPTURED --from 2026-09-01 --to 2026-09-25Flag của pg order list | Kiểu | Mô tả |
|---|---|---|
--status | string | Ví dụ CAPTURED, CANCELLED, AUTHENTICATION_NOT_NEEDED; sai giá trị thì lệnh liệt kê các giá trị hợp lệ |
--from, --to | string | Khoảng ngày YYYY-MM-DD |
--search | string | Tìm theo mã đơn hoặc số hóa đơn |
--customer | string | ID khách hàng |
--page, --per-page | int | Phân trang; tối đa 100 |
Xem đơn trên production
pg order list và pg order get chạy cả trên production. Hai lệnh chỉ đọc nên không hỏi xác nhận, và default_env: production cũng tính. CLI đọc đơn bằng phiên đăng nhập của bạn, không dùng khóa merchant:
$ sepay pg order list --env production --status CAPTURED --from 2026-11-01 --to 2026-11-09 -o json$ sepay pg order get INV-1001 --env production -o json- Token cần scope
pg-order:read; thiếu thì lệnh dừng với exit code 5 và báotoken lacks the required scope, run: sepay auth refresh --scopes pg-order:read. - Tài khoản cần quyền Cổng thanh toán trong công ty; thiếu thì exit code 8,
your account lacks permission for this action; ask an admin of your company. - Số tiền là số nguyên (VND), ví dụ
"order_amount": 150000; cộtAMOUNTcủa bảng in150.000. pg order getinMETHOD TYPE AMOUNT STATUS CARD DATEkhi đơn có giao dịch. Với giao dịch thẻ,-o jsonchỉ có hãng thẻ và 4 số cuối,"card": { "brand": "VISA", "last4": "1234" }; không có số thẻ, tên chủ thẻ, ngày hết hạn.payment_methodcủa mỗi giao dịch là phương thức của đơn.-o jsoncủalistlà một mảng, không kèm thông tin trang. Đọc hết các trang bằng--page 1, 2, …với cùng--per-page(mặc định 20), dừng ở trang có ít dòng hơn--per-page, hoặc khi trang mới bắt đầu bằng đúngorder_invoice_numbercủa trang trước. Đơn mới tạo trong lúc đọc làm lệch trang, nên giữ mỗiorder_invoice_numbermột dòng.
Hủy đơn, void giao dịch thẻ trên production chưa có trong CLI.
pg order cancel và pg order void
Chọn lệnh theo loại đơn và trạng thái thanh toán:
| Trường hợp | Lệnh |
|---|---|
| Chuyển khoản (kể cả NAPAS VietQR), khách chưa trả | sepay pg order cancel HD1709 |
Thẻ, đã thanh toán (CAPTURED), chưa quyết toán | sepay pg order void HD1709 |
| Thẻ, đã quyết toán | Không có lệnh CLI; hoàn tiền qua API |
cancel bị từ chối khi đơn đã CAPTURED hoặc CANCELLED. void bị từ chối khi sai loại đơn, hoặc khi giao dịch thẻ đã qua mốc quyết toán (API hủy giao dịch). Xem loại đơn và trạng thái bằng pg order get trước khi chạy.
Cả hai lệnh hỏi xác nhận trước khi chạy, kể cả trên sandbox, và không có lệnh nào hoàn tác.
Mã lỗi
| Thông báo hoặc mã | Exit / error_code | Nguyên nhân |
|---|---|---|
no IPN endpoint configured, IPN delivery is off (pg ipn listen) | Cảnh báo, lệnh vẫn chạy | Chưa đặt IPN URL, hoặc đã tắt bằng --active=false (pg ipn set <url> --active bật lại) |
this company has no active Payment Gateway merchant (pg ipn listen) | Cảnh báo, lệnh vẫn chạy | Công ty chưa có merchant Cổng thanh toán đang hoạt động; kiểm tra bằng pg merchant get |
pg ipn set từ chối URL | 1 / mã do server trả | URL là localhost hoặc địa chỉ nội bộ; handler trên máy bạn vẫn nhận IPN qua pg ipn listen |
Lỗi --amount, --invoice hoặc URL (checkout init) | 2 / usage_error | Số tiền không phải số nguyên; số hóa đơn chứa /, dấu chấm, khoảng trắng hoặc chữ có dấu; URL thiếu scheme như https://, kể cả dạng localhost:3000/done (must include a scheme, sửa thành http://localhost:3000/done), hoặc dùng scheme bị chặn (scheme "vbscript" is not allowed) |
--payment-method CARD is not active on this sandbox merchant (checkout init) | 1 / error | Phương thức chưa bật trên merchant; thông báo liệt kê các phương thức đang bật |
4000, 4001, 4002 (void) | 1 / 4000, 4001, 4002 | Đơn chưa thanh toán, đã hủy từ trước, hoặc không có giao dịch |
Đã có lỗi xảy ra, vui lòng liên hệ SePay để được hỗ trợ. (void) | 1 | Đơn chuyển khoản; void chỉ dùng cho đơn thẻ |