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 onPay 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ểu | Bắt buộc | Mô tả |
|---|---|---|---|
<prefix> hoặc --prefix | string | Có | 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-type | string | Không | NumberOnly (chỉ số) | NumberAndLetter (số và chữ) |
--suffix-from | int | Không | Độ dài hậu tố tối thiểu, 1 đến 30 |
--suffix-to | int | Không | Độ dài hậu tố tối đa, 1 đến 30; không nhỏ hơn --suffix-from |
--enable, --disable | bool | Không | Bật, tắt nhận diện mã thanh toán cho cả công ty |
--structure | string | Không | Tiề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 |
--active | bool | Không | Mặ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 onGhi 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ó
--structurethì 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ùngpaycode 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 updatekhô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 listlàpaycode ls,paycode updatelàpaycode edit. - Trên production, lệnh in
env: production, rồi! live: update pay code targets PRODUCTIONvà hỏi xác nhận. Script bạn tự viết cần đủ--structure <prefix>,--env productionvà--yes;--enable,--disablechỉ chạy trong terminal (luật xác nhận). Thiếu scopepaycode:writethì 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.
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ểu | Bắt buộc | Mô tả |
|---|---|---|---|
<prefix> hoặc --prefix | string | Có | 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-type | string | Có | NumberOnly (chỉ số) | NumberAndLetter (số và chữ) |
--suffix-from | int | Có | Độ dài hậu tố tối thiểu, 1 đến 30 |
--suffix-to | int | Có | Độ dài hậu tố tối đa, 1 đến 30; không nhỏ hơn --suffix-from |
--active | bool | Có | --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 onGhi 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ùngsepay 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-keynhư ở 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;--yeskhông xác nhận được. Cấu trúc tạo với--activekhớ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ượng | Nguyê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_exists | paycode 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 |