English
Payment Elf: Design Architecture
This page explains the role Payment Elf plays on the POS computer, how requests reach the platform, and how local data relates to platform data. For installation see Installation and Sign-In.
Components and Chain
| Role | Responsibility | Boundary |
|---|---|---|
| Payment Elf | Reads the payment code, recognizes the amount, starts payments, announces and prints, keeps the local ledger | Only handles collection; does not modify the POS software |
| Payment platform | Starts and decides payments, refunds and order queries, and keeps the transaction truth | The only source of transaction truth; the local ledger is only a mirror |
| Barcode scanner | Outputs the payment code through HID keyboard emulation or HID POS | Reads the payment code in the background |
| Printer / speaker | Outputs receipts and voice | Failures only prompt; they never interrupt collection |
Payment Elf connects directly to the DaxPay backend and does not go through the cashier-system gateway. The stack is C# / WPF / .NET 10 (net10.0-windows); OCR uses OnnxRuntime with a local v7 tiny model, printing is a self-built ESC/POS implementation, and the local ledger uses Microsoft.Data.Sqlite.
Amount Chain and Payment Chain
The two chains are separate, and the amount source does not affect how the payment request is judged.
| Chain | Input | Processing | Output |
|---|---|---|---|
| Amount chain | Payment code from the barcode scanner, manual entry on the calculator panel, OCR of the screen amount | The amount is shown on the floating bar once stable and confirmed by the operator; auto-collection is off by default | Amount due and payment code |
| Payment chain | Payment code + amount | Calls the platform barcode payment API and polls for the result | Success / failure / in progress, written to the local ledger |
Payment endpoints:
| Method and path | Purpose |
|---|---|
POST /elf/cashier/pay-by-auth-code | Starts a barcode-initiated payment with the payment code |
GET /elf/cashier/order-status | Queries the order status |
GET /elf/cashier/config-options | Pulls configuration items such as stores, apps and terminals |
POST /elf/order/refund | Starts a refund |
POST /elf/order/close | Close-order API; the desktop app exposes no close-order entry |
Requests always carry the Accesstoken, x-client-code: merchant and x-terminal: elf headers and use the merchant identity domain.
When the barcode payment returns wait / progress, poll every 1.5 seconds for up to 20 seconds, adding sync=true on every third attempt to force a sync with the platform. When an HTTP response is lost, recover by querying with bizOrderNo; never start the payment twice.
Local Ledger and Platform Source of Truth
- The platform is the source of transaction truth: payment, refund and close-order states ultimately follow the platform;
- The local ledger (
trades.db) is only a mirror, used for offline history, the trade record list and receipt reprints; - On refunds the local ledger checks the refundable balance, but the platform result is final;
- Unpaid orders are closed automatically by the platform on expiry, and the desktop app exposes no close-order entry;
- History is viewable offline, but collection, refund and order query need the platform to be reachable.
Printing and Voice Fallbacks
Printing: 58 / 80mm paper widths, three channels — driver-free USB, network RAW TCP (default 9100) and file dump (debugging) — with 1 to 4 copies. All layout is aligned with ESC/POS commands, never space padding; encoding is GB18030; QR codes and barcodes are rendered as bitmaps. A print failure only prompts and does not interrupt cashiering; use "Reprint last" to print again.
Voice: when the system Chinese voice pack is available, TTS synthesizes the amount; when it is not, the app falls back to concatenating the built-in WAV word list so the broadcast never stops.
Design Constraints
- No changes to the POS software: it only reads the payment code and screen amount alongside, and the POS software keeps its own books;
- Barcode-initiated payment only: this version does not include merchant-presented QR, so scenarios where the merchant shows a collection code do not apply;
- Receipt templates stay local: built-in templates only, with no server-side template management;
- Terminal choice is stored locally only: reselect after switching computers, reinstalling or clearing configuration;
- Close-order goes through the platform only: the desktop app exposes no close-order entry, and unpaid orders are closed by the platform on expiry;
- Source delivery: the source code is delivered as source with the Ecosystem Extension Pack (source-code license included).