Khi việc bạn cần làm chưa có lệnh riêng trong SePay CLI, gọi thẳng endpoint của SePay API bằng sepay api <đường dẫn>. Lệnh dùng phiên đăng nhập của sepay login, không cần API Token, và gọi tới môi trường đang chọn (sandbox mặc định, --env production cho dữ liệu thật).
sepay api chỉ gọi SePay API. Cổng thanh toán, Bank Hub và Hóa đơn điện tử dùng nhóm lệnh riêng: pg, bankhub, einvoice.
Đọc dữ liệu
Đường dẫn tính từ địa chỉ gốc của API, ví dụ /transactions: không dán cả URL, không lặp lại /v2. Với GET, mỗi -f key=value thành một tham số trên URL. Lấy giao dịch mới nhất:
$ sepay api /transactions -f per_page=1env: sandbox{"status": "success","data": [ { "id": "07ad3dc9-xxxx-xxxx-xxxx-0afffe87053b", "transaction_date": "2026-10-31 11:24:40", "account_number": "0000000002", "va": "", "transfer_type": "in", "amount_in": 50000, "amount_out": 0, "accumulated": 0, "transaction_content": "Giao dich sandbox 31/10/2026 11:24:40", "reference_number": "SBCF7A82A9EBC8", "code": "DH1709", "bank_brand_name": "ACB", "bank_account_id": "d6719d04-xxxx-xxxx-xxxx-a6006ab65aca", "va_id": null, "webhook_success": 8 }],"meta": { "pagination": { "total": 48, "per_page": 1, "current_page": 1, "last_page": 48, "has_more": true }}}CLI in nguyên JSON mà API trả về, kể cả khi không có --json; -o yaml in cùng dữ liệu dạng YAML. Ý nghĩa từng trường và tham số lọc có ở trang của endpoint, ví dụ Danh sách giao dịch.
Ghi dữ liệu
Chọn phương thức bằng -X. Với POST, PUT, DELETE, các -f gộp thành body JSON. Giá trị là JSON hợp lệ (42, true, [1,2]) được gửi đúng kiểu, còn lại gửi dạng chuỗi. Tạo một webhook trên sandbox:
$ sepay api /webhooks -X POST -f url=https://example.com/hook -f bank_mode=all -f event_type=in -f is_verify_payment=trueAPI trả về webhook vừa tạo dạng JSON, gồm id của webhook.
Body dài hơn thì đọc từ tệp JSON bằng --input, hoặc --input - để đọc từ stdin. --input không dùng chung với -f và không dùng với GET:
$ sepay api /webhooks -X POST --input body.json| Flag | Kiểu | Mô tả |
|---|---|---|
-X, --method | string | Phương thức HTTP. Mặc định GET |
-f, --field | string[] | Một trường key=value; lặp flag để thêm nhiều trường |
--input | string | Đọc body JSON từ tệp, hoặc - để đọc từ stdin |
-H, --header | string[] | Thêm header Tên: giá trị cho request; lặp flag để thêm nhiều header |
Mỗi lần chạy, lệnh ghi gửi kèm một idempotency key mới, nhờ đó CLI tự gửi lại an toàn khi mất kết nối giữa chừng. Chạy lại cả lệnh là một key mới; muốn chạy lại mà không tạo trùng, truyền cùng --idempotency-key ở cả hai lần, xem Idempotency.
Trên production
-X DELETE hỏi xác nhận trên mọi môi trường. Trên production, mọi method khác GET, HEAD là lệnh sửa dữ liệu và theo luật xác nhận: cần --env production trên lệnh, in dòng env: production, dòng ! live: … rồi hỏi xác nhận:
$ sepay api /webhooks/<webhook-xid> -X DELETE --env productionenv: production! live: api DELETE /webhooks/<webhook-xid> targets PRODUCTION? api DELETE /webhooks/<webhook-xid> on production? [y/N]Script bạn tự viết chạy được với --env production và --yes khi đoạn cuối của path là id (UUID hoặc số), như ví dụ trên. Path không kết thúc bằng id, như POST /webhooks hay POST /bank-accounts/<xid>/va, là tạo mới: chỉ chạy trong terminal, --yes không xác nhận được. Thêm --dry-run để in request sẽ gửi mà không gửi gì, kể cả GET.
sepay api bỏ qua các kiểm tra mà lệnh riêng có, kể cả việc chặn production của những lệnh chỉ chạy trên sandbox. Khi việc cần làm đã có lệnh riêng trong Danh sách lệnh, dùng lệnh đó.