Cổng thanh toán trong SePay CLI

Dùng SePay CLI với Cổng thanh toán: tạo đơn và nhận IPN về localhost trên sandbox để kiểm tra handler, xem danh sách và chi tiết đơn trên production.

||
Production chỉ có lệnh xem đơn

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:

Code
1
pg ipn set → pg ipn listen → pg checkout init → (khách trả) → pg order get
  • sepay webhook listen không nhận thông báo của đơn Cổng thanh toán; nhóm này dùng pg ipn listen.
  • Lệnh pg order nhậ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  yes

pg 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ểuBắt buộcMô tả
<url>stringCó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ộ
--secretstringKhôngChuỗi tự đặt, SePay gửi trong header X-Secret-Key; - đọc từ stdin. Có --secret thì xác thực tự bật
--activeboolKhông--active bật, --active=false tắt việc gửi IPN
--auth-typestringKhôngSECRET_KEY, hoặc để trống để tắt xác thực
--content-typestringKhôngKiể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:   yes

Mỗ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ố

FlagKiểuBắt buộcMô tả
--forwardstringTrong scriptĐịa chỉ handler. Trong terminal, bỏ trống thì CLI hỏi
--printboolKhôngIn toàn bộ payload
--eventsstring[]KhôngChỉ chuyển các loại ORDER_PAID, TRANSACTION_VOID
--orderstringKhôngChỉ 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=HD1709

order= 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.
  • --headers in 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 định 7, tối đa 10; 0 là một lần). CLI chỉ gửi lại khi handler nằm trên máy bạn. Dừng listen thì 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ố

FlagKiểuBắt buộcMô tả
--amountstringCóSố tiền VND, số nguyên: lớn hơn 0 với PURCHASE, bằng 0 với VERIFY
--descriptionstringCóMô tả đơn
--invoicestringVới PURCHASESố hóa đơn: chữ không dấu, số, -, _; tối đa 100 ký tự
--operationstringKhôngPURCHASE (mặc định) | VERIFY
--payment-methodstringKhôngBANK_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-urlstringKhôngURL 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
--currencystringKhôngChỉ nhận VND (mặc định)
--customerstringKhôngID khách hàng
--no-openboolKhôngChỉ 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:

Trang thanh toán sandbox mở ra sau khi tạo đơn: khách chọn thẻ, VietQR hoặc NAPAS VietQR
Nhấn để phóng to
Trang thanh toán sandbox mở ra sau khi tạo đơn: khách chọn thẻ, VietQR hoặc NAPAS VietQR

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 VND

Order 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-25
Flag của pg order listKiểuMô tả
--statusstringVí dụ CAPTURED, CANCELLED, AUTHENTICATION_NOT_NEEDED; sai giá trị thì lệnh liệt kê các giá trị hợp lệ
--from, --tostringKhoảng ngày YYYY-MM-DD
--searchstringTìm theo mã đơn hoặc số hóa đơn
--customerstringID khách hàng
--page, --per-pageintPhâ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áo token 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ột AMOUNT của bảng in 150.000.
  • pg order get in METHOD TYPE AMOUNT STATUS CARD DATE khi đơn có giao dịch. Với giao dịch thẻ, -o json chỉ 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_method của mỗi giao dịch là phương thức của đơn.
  • -o json của list là 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 đúng order_invoice_number của trang trước. Đơn mới tạo trong lúc đọc làm lệch trang, nên giữ mỗi order_invoice_number mộ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ợpLệ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ánsepay pg order void HD1709
Thẻ, đã quyết toánKhô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.

Đơn đã hủy và giao dịch đã void không khôi phục được

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_codeNguyên nhân
no IPN endpoint configured, IPN delivery is off (pg ipn listen)Cảnh báo, lệnh vẫn chạyChư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ạyCô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 URL1 / 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_errorSố 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 / errorPhươ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ẻ