Mã thanh toán trong SePay CLI

Xem, sửa và thêm cấu trúc mã thanh toán bằng SePay CLI để chuyển khoản tự khớp đơn hàng theo nội dung, rồi thử nhận diện mã trên sandbox.

||

Muốn khoản chuyển khoản tự khớp với đơn hàng theo nội dung, đặt cấu trúc mã thanh toán bằng paycode (một công ty có thể có nhiều cấu trúc, mỗi cấu trúc một tiền tố): SePay đọc mã từ nội dung chuyển khoản và trả về trường code của webhook. Cách còn lại là cho mỗi đơn một số tài khoản riêng, xem Tài khoản ảo (VA).

Đọc thêm ở Cấu hình mã thanh toán; cách đọc code trong webhook có ở Tích hợp webhook.

Các lệnh chạy trên cả sandbox và production. Trên production, paycode update và paycode create cần scope paycode:write, các lệnh xem cần read. Bạn cần đăng nhập.

paycode list

Xem cấu trúc mã thanh toán hiện tại.

$ sepay paycode listPay code: onPREFIX        FROM        TO        TYPE              ACTIVEDH            4           10        NumberOnly        on

Pay code cho biết nhận diện mã thanh toán đang bật (on) hay tắt (off) cho cả công ty.

paycode update

Đặt cấu trúc mã thanh toán: tiền tố cố định (ví dụ DH) và độ dài hậu tố.

Tham số

Tham sốKiểuBắt buộcMô tả
<prefix> hoặc --prefixstringCóTiền tố, 2 đến 5 chữ cái; SePay lưu chữ hoa và khớp không phân biệt hoa thường. --prefix dùng khi tiền tố trùng từ khóa on, off, yes, no, true, false
--character-typestringKhôngNumberOnly (chỉ số) | NumberAndLetter (số và chữ)
--suffix-fromintKhôngĐộ dài hậu tố tối thiểu, 1 đến 30
--suffix-tointKhôngĐộ dài hậu tố tối đa, 1 đến 30; không nhỏ hơn --suffix-from
--enable, --disableboolKhôngBật, tắt nhận diện mã thanh toán cho cả công ty
--structurestringKhôngTiền tố hiện tại của cấu trúc cần sửa, khi công ty có nhiều cấu trúc
--activeboolKhôngMặc định true. --active=false chỉ tắt cấu trúc đang sửa

Ví dụ

$ sepay paycode update DH --character-type NumberOnly --suffix-from 4 --suffix-to 10env: sandboxPay code updated.Pay code: onPREFIX        FROM        TO        TYPE              ACTIVEDH            4           10        NumberOnly        on

Ghi chú

  • Flag nào bạn bỏ qua thì giữ giá trị hiện có. Công ty chưa có cấu trúc nào thì phải truyền tiền tố, và lệnh tạo cấu trúc mặc định: hậu tố 3 đến 10 ký tự, NumberOnly.
  • Lệnh sửa một cấu trúc, giữ nguyên các cấu trúc khác. Không có --structure thì CLI hỏi cấu trúc cần sửa khi chạy trong terminal và công ty có nhiều cấu trúc; chạy trong script thì sửa cấu trúc đang bật đầu tiên. Truyền tiền tố khác thì lệnh đổi tiền tố của cấu trúc đó; muốn thêm cấu trúc mới thì dùng paycode create.
  • Chỉ truyền flag (không truyền tiền tố) thì tiền tố đang lưu được giữ nguyên.
  • Chạy sepay paycode update không kèm tham số trong terminal thì CLI hỏi muốn sửa gì (tiền tố, độ dài hậu tố, loại ký tự, bật/tắt cấu trúc, bật/tắt nhận diện), kèm giá trị đang lưu của từng mục.
  • Viết tắt: paycode list là paycode ls, paycode update là paycode edit.
  • Trên production, lệnh in env: production, rồi ! live: update pay code targets PRODUCTION và hỏi xác nhận. Script bạn tự viết cần đủ --structure <prefix>, --env production và --yes; --enable, --disable chỉ chạy trong terminal (luật xác nhận). Thiếu scope paycode:write thì lệnh thoát với exit code 5.
  • Khi bạn đổi hoặc bỏ một tiền tố mà kết nối Haravan, Shopify hay Sapo vẫn còn dùng, lệnh in cảnh báo Warning: ... connection(s) still use a pay code prefix this list no longer has. Sửa tiền tố trong các kết nối đó trên my.sepay.vn.
Đổi cấu trúc trên production có hiệu lực ngay

Khoản khách đang chuyển với tiền tố cũ vẫn vào tài khoản nhưng không còn tự khớp với đơn. Tìm và đối chiếu các khoản này bằng sepay transaction list (xem Giao dịch).

paycode create

Thêm một cấu trúc mã thanh toán vào cuối danh sách, ví dụ khi đơn từ website dùng tiền tố DH còn đơn từ ứng dụng dùng APP. Các cấu trúc khác và công tắc bật, tắt nhận diện của công ty giữ nguyên; muốn đổi chúng thì dùng paycode update.

Tham số

Tham sốKiểuBắt buộcMô tả
<prefix> hoặc --prefixstringCóTiền tố mới, 2 đến 5 chữ cái, chưa có trong công ty (không phân biệt hoa thường). Chạy trong terminal mà không truyền thì CLI hỏi
--character-typestringCóNumberOnly (chỉ số) | NumberAndLetter (số và chữ)
--suffix-fromintCóĐộ dài hậu tố tối thiểu, 1 đến 30
--suffix-tointCóĐộ dài hậu tố tối đa, 1 đến 30; không nhỏ hơn --suffix-from
--activeboolCó--active để cấu trúc khớp giao dịch ngay, --active=false để tạo sẵn ở trạng thái tắt

Ví dụ

$ sepay paycode create APP --character-type NumberOnly --suffix-from 4 --suffix-to 8 --active✓ Created pay code structure APP.Pay code: onPREFIX        FROM        TO        TYPE              ACTIVEDH            4           10        NumberOnly        onAPP           4           8         NumberOnly        on

Ghi chú

  • Lệnh không có giá trị mặc định. Trong terminal, CLI hỏi tham số còn thiếu. Trong script, thiếu hoặc sai một tham số thì lệnh thoát với exit code 2 và chưa gửi gì lên SePay.
  • Tiền tố đã có thì lệnh báo lỗi paycode_prefix_exists. Muốn sửa cấu trúc đó, dùng sepay paycode update --structure <prefix>.
  • Chạy lại lệnh sau khi mất kết nối không tạo trùng cấu trúc. Trong script, truyền --idempotency-key như ở Idempotency.
  • Trên production, lệnh in ! live: create pay code structure APP targets PRODUCTION (tên tiền tố của bạn) rồi hỏi xác nhận trước khi tạo. Lệnh tạo không có id nên trên production chỉ chạy trong terminal; --yes không xác nhận được. Cấu trúc tạo với --active khớp giao dịch ngay.

Kiểm tra kết quả khớp trên sandbox

Mở webhook listen để xem code của webhook, rồi giả lập giao dịch bằng sandbox simulate.

Thử cấu trúc mã thanh toán: đặt mã vào nội dung giao dịch bằng --override content=.... SePay nhận diện mã từ nội dung như với giao dịch thật:

$ sepay sandbox simulate payment_in --bank-account <bank-account-xid> --amount 50000 --override content="DH1709 thanh toan don hang"

--code DH1709 chỉ điền sẵn trường code của webhook, không đi qua cấu trúc mã thanh toán, nên không cho biết cấu hình của bạn có nhận diện đúng mã hay không. --code nhận tối đa 10 ký tự; mã dài hơn thì thử bằng --override content=....

Tra giao dịch theo mã bằng sepay transaction list --search DH1709. Thử VA thì xem Thử VA trên sandbox.

Thông báo lỗi

Thông báo hoặc hiện tượngNguyên nhân
code trống trong webhook dù khách ghi mãNhận diện đang tắt, mã sai cấu trúc, hoặc ngân hàng cắt bớt nội dung (đối chiếu với paycode list)
paycode_prefix_existspaycode create dùng tiền tố công ty đã có; đổi tiền tố, hoặc sửa cấu trúc đó bằng paycode update --structure <prefix>
--suffix-from is required (hoặc flag khác)Chạy trong script, paycode create cần đủ --suffix-from, --suffix-to, --character-type và --active