Skip to content
LionPOS

POS and payment webhooks

POS HTTP API

Section titled “POS HTTP API”
  • PosController — @Controller('pos') → /api/v1/pos (global API prefix).
  • Auth: AuthJwtGuard — accepts admin or vendor JWTs (see file-level comment in pos.controller.ts). Swagger tag: POS (vendor + admin).
  • store_id: optional on many handlers; when omitted, PosService.resolveStoreIdForActor picks the active store. If none exists, list endpoints may return empty data with store_id: null; placing an order can return 400 no_store_available.
  • Money side: POST /pos/orders persists orders and related finance rows per service comments (receivables / debt flags when applicable). Vendor expense flows stay under vendor finance APIs, not POS.

Terminal payment webhook (server-to-terminal)

Section titled “Terminal payment webhook (server-to-terminal)”
  • PosPaymentWebhookController — @Controller('pos/payments') → /api/v1/pos/payments.
  • Route: POST /pos/payments/terminal-webhook (excluded from Swagger via @ApiExcludeEndpoint — treat as integration surface, not public UI).
  • Headers: optional x-pos-terminal-key — passed into PosService.handleTerminalPaymentWebhook for per-store terminal API key validation (see unit tests in pos.service.spec.ts for invalid-key rejection).
  • Body: TerminalPaymentWebhookDto — validate against DTO / service behavior when integrating a physical terminal or PSP callback. Optional entry_mode, card_last4, card_exp, and terminal_transaction_at (ISO-8601) are stored in terminal_payment_meta for receipt lines (ACCT / CARD / DATE/TIME); optional signal_data (PAX-style index,level segments joined by ^, from EcrHubResult.normalized.signalData) is merged into terminal_payment_meta and summarized on the receipt SIG line. The WebSocket payment_result uses camelCase aliases (entryMode, cardLast4, cardExp, terminalTransactionAt) mapped by the pos-bridge service.

For PSP-specific retry schedules, signature algorithms, and idempotency guarantees, document against your payment provider and the behavior inside PosService.handleTerminalPaymentWebhook (unit tests in pos.service.spec.ts cover invalid keys).

Section titled “Related”