Skip to content

Payment Elf: Design Architecture ​

Updated: 11/10/26, 10:51:10 AM

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 ​

RoleResponsibilityBoundary
Payment ElfReads the payment code, recognizes the amount, starts payments, announces and prints, keeps the local ledgerOnly handles collection; does not modify the POS software
Payment platformStarts and decides payments, refunds and order queries, and keeps the transaction truthThe only source of transaction truth; the local ledger is only a mirror
Barcode scannerOutputs the payment code through HID keyboard emulation or HID POSReads the payment code in the background
Printer / speakerOutputs receipts and voiceFailures 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.

ChainInputProcessingOutput
Amount chainPayment code from the barcode scanner, manual entry on the calculator panel, OCR of the screen amountThe amount is shown on the floating bar once stable and confirmed by the operator; auto-collection is off by defaultAmount due and payment code
Payment chainPayment code + amountCalls the platform barcode payment API and polls for the resultSuccess / failure / in progress, written to the local ledger

Payment endpoints:

Method and pathPurpose
POST /elf/cashier/pay-by-auth-codeStarts a barcode-initiated payment with the payment code
GET /elf/cashier/order-statusQueries the order status
GET /elf/cashier/config-optionsPulls configuration items such as stores, apps and terminals
POST /elf/order/refundStarts a refund
POST /elf/order/closeClose-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).