English
Payment Elf: Collection, Broadcast and Accounting
Screen Amount Recognition (OCR)
On first use, box-select the total amount area of the POS software under "Cashier Settings → Collection Config", and recognition runs automatically afterwards:
- Re-select after a display scaling or resolution change; selecting again starts from the last position;
- "Test Recognition" verifies the current selection immediately;
- On failure it silently falls back to manual input and never guesses the amount;
- Auto-collection is off by default. When enabled, a confidence threshold can be set; below it, manual confirmation is still required;
- Same-amount suppression: within 10 seconds of a successful collection, auto-collection of the same amount is routed back to manual confirmation.
OCR uses OnnxRuntime with a local v7 tiny model; recognition runs on the device.
Barcode-Initiated Payment
When the barcode scanner reads the customer's payment code, the code goes straight into the cashier. The cashier also offers a calculator-style panel for entering the amount by hand. After confirming, it calls the platform to start the barcode payment and waits for the result:
- Success: the amount is announced by voice and a receipt prints per settings;
- In progress: waiting continues for the platform to return a final state;
- Failure or order closed: the failure reason is shown, and an unknown state is never treated as success.
The barcode scanner supports both HID keyboard emulation and HID POS. After plugging in the device, select it under "Cashier Settings → Barcode Scanner" and scan a payment code to test. Scanning keeps working while Payment Elf runs in the background.
When the platform returns wait / progress, poll every 1.5 seconds for up to 20 seconds, adding sync=true on every third attempt to force a sync. When an HTTP response is lost, recover by querying with bizOrderNo; never start the payment twice.
Desktop Form
- Floating amount bar: drag with the left button, resize with the bottom-right handle, double-click to open the cashier; the context menu offers the cashier, the main window, theme switching and exit. Opacity and position are adjusted under "Cashier Settings → General" and remembered;
- Global hotkeys: by default
Ctrl+Alt+Dopens the cashier andCtrl+Alt+Sthe main window; "Reprint last" and "Open / collapse trade records" are unset by default and can be recorded under "Cashier Settings → Hotkeys"; - Cashier shortcuts:
Enterin the amount box with no payment code jumps to the payment code, otherwise it confirms the collection;Eschides;Tab/Shift+Tabswitch between amount and payment code;Ctrl+Backspaceclears the amount;Ctrl+Preprints the last one;F1shows the shortcut list; - Tray: the program stays in the tray, double-click opens the cashier, and the context menu offers the cashier, the main window and exit; the tray "Exit" is the only way to fully quit the program.
Broadcast and Receipts
Voice broadcast: on success the amount is announced. When the system Chinese voice pack is available, TTS is used; otherwise it falls back to concatenating the built-in WAV word list. Switch, volume and output device are adjusted under "Cashier Settings → Voice Broadcast".
Receipt printing: enable printing and choose a channel under "Cashier Settings → Printer":
| Channel | Description |
|---|---|
| USB printer (driver-free) | Select the USB receipt printer directly; no printer driver needed |
| Network printer | Enter the printer IP and port; the port defaults to 9100 |
| File dump | Debug channel; print commands are written to print-dump in the data directory and it is not shown in the settings UI |
Paper width is 58mm or 80mm, and the built-in layout adapts to it; copies are 1 to 4 and changes take effect immediately. The settings page can print a test page; a successful collection prints automatically, and a print failure only prompts without interrupting cashiering.
Refunds, Order Queries and Reprints
Act on a collection row under "Trade Records → Collections":
- Refund: full or partial refunds; the local ledger checks the refundable balance, and the platform is authoritative;
- Order query: actively query the platform and sync the latest order status;
- Refund records: shown read-only under "Trade Records → Refunds" and linked to the original collection;
- Reprint last: a global hotkey reprints the receipt of the latest successful collection today, still available after a restart.
Unpaid orders are closed automatically by the platform on expiry; cashiers do not handle them by hand.
Accounting Rules
- The platform is the source of transaction truth: payment, refund and close-order states ultimately follow the platform;
- The local ledger is only a mirror, used for offline history, trade records and receipt reprints;
- The local check on refund amounts is only an early interception; the platform decision takes effect;
- Receipt layouts use the built-in local template; server-side template management is not supported.
Field Issues
No receipt prints
First print a test page under "Cashier Settings → Printer", then check in order: whether the printer is powered on, the USB is connected or the network port is reachable; whether the channel is right — the USB channel needs the correct device selected, and the network channel needs the IP, the port (default 9100), the same subnet as the POS computer and firewall clearance; whether the paper width matches the actual paper. A print failure only prompts; use "Reprint last" to print again.
OCR amount recognition is inaccurate
Box-select the amount area of the POS software again; re-select after any display scaling, resolution or POS-software theme change, and use "Test Recognition" to verify the current area. Auto-collection is off by default; when enabled, values below the confidence threshold still require manual confirmation, and same-amount auto-collections within 10 seconds of a successful collection are routed back to manual confirmation.
The barcode scanner does nothing
Under "Cashier Settings → Barcode Scanner", confirm the device is selected; after switching to HID mode, unplug and replug; confirm scan listening is enabled. Do not run several scan-listening tools at once, or the input may be captured by the POS software or another tool.