Cấu hình terminal thanh toán

import { Aside } from ‘@astrojs/starlight/components’;

Tình huống sử dụng

Cashier cần quẹt thẻ cho khách ngay tại quầy. Bài viết này dành cho chủ cửa hàng / người cấu hình (không phải cashier bán hàng).

Sau khi cấu hình xong, cashier mở màn Bán hàng → chọn phương thức Thẻ → hệ thống gọi tới terminal qua bridge trên Vendor Desktop → khách quẹt → kết quả đổ về.

Source: apps/vendor-web/src/app/point-of-sale/pages/settings/settings-hardware-terminal-page.tsx + <DeviceSettings hardwareFocus="terminals" />.

Terminal thanh toán — hub thiết bị Hình: Trang cấu hình terminal — danh sách thiết bị PAX LAN / CodePay WS, badge “Local ECE ready”, nút kích hoạt bridge. Spec owner: cashier-screenshots.spec.ts → "settings — terminal payment".

Trước khi bắt đầu

Vendor Desktop phải chạy trên PC quầy — terminal liên lạc qua bridge trên app này.
Cashier chỉ cần quyền pos ghi để bán; cấu hình thiết bị cần settings ghi (chỉ chủ).
Biết IP + port của terminal PAX, hoặc URL WebSocket của CodePay.

4 bước cấu hình

Bước 1 — Mở trang terminal

Từ shell Thu ngân → Cài đặt → Terminal (/point-of-sale/settings/terminal).

Nếu cashier không thấy mục này, chủ cần cấp settings ghi (xem FAQ — quyền & vai trò).

Bước 2 — Thêm thiết bị

Click + Thêm thiết bị → chọn loại Terminal thanh toán.

Form yêu cầu:

Trường	Mô tả
Tên	Tên hiển thị (ví dụ “PAX Quầy 1”)
Hãng	`PAX` (LAN) hoặc `CODEPAY` (WebSocket)
Phương thức	`LAN` / `TCP` cho PAX, `WEBSOCKET` cho CodePay
IP	Địa chỉ IP của terminal trong mạng LAN
Port	Cổng TCP (mặc định PAX: `10009`)
WebSocket URL	URL `wss://...` cho CodePay

Source: apps/vendor-web/src/components/dashboard/settings/device-settings-form.schema.ts.

Bước 3 — Bật thiết bị

Trên thẻ thiết bị vừa thêm, gạt toggle Bật/Tắt sang xanh (getDeviceActive(device)). Thiết bị tắt sẽ không được gọi khi bán.

Bước 4 — Kích hoạt bridge

Sau khi lưu, component hiển thị 1 trong 2 trạng thái:

Helper kiểm tra: canOpenPosBridgeActivate — yêu cầu IP + port (LAN) hoặc wss:// URL hợp lệ (CodePay).

Hai loại thiết bị

Loại	Hãng	Phương thức	Ưu tiên dùng khi
PAX LAN	`PAX`	`TCP`	Terminal cùng mạng LAN với PC quầy, ổn định, không phụ thuộc internet
CodePay WS	`CODEPAY`	`WEBSOCKET`	Terminal ở xa (chi nhánh khác), hoặc dùng gateway cloud

isCodepayWsCard được detect khi manufacturer là CODEPAY, method WEBSOCKET, và terminalWsUrl match ^wss?://.

Kết quả mong đợi

Trên màn Bán hàng → chọn Thẻ → popup terminal nhận lệnh từ bridge.
Sau khi khách quẹt, kết quả (thành công / thất bại) đổ về UI trong vài giây.
Kết quả cuối cùng tạo 1 transaction trong đơn — cashier không bấm gì thêm để tránh double-charge.

Lỗi thường gặp

Triệu chứng	Xử lý
Thẻ device xám, không bật được toggle	Chưa nhập IP/port hoặc CodePay URL — kiểm tra lại form
Báo “bridgeActivate failed”	Vendor Desktop chưa chạy, hoặc bridge chưa kết nối server
Bán thẻ nhưng spinner treo	Xem FAQ — In & thiết bị → Thanh toán kẹt
CodePay URL không match `wss?://`	Helper sẽ không coi là CodePay WS — kiểm tra URL scheme

Kỹ thuật liên quan

Component: <DeviceSettings hardwareFocus="terminals"> (apps/vendor-web/src/components/dashboard/settings/DeviceSettings.tsx)
API: fetchVendorDevicesSettings, patchVendorDevicesSettings (apps/vendor-web/src/services/vendor-settings.api.ts)
Bridge: postVendorPosBridgeActivateFromDevice + DevicePosBridgePersistedPanel