Skip to main content

Business Flows

This section describes the key business processes in My-Scan from a functional point of view, what happens during a shopping trip, and why, independent of the specific API calls involved.

Shopping Trip​

A My-Scan shopping trip has five stages:

  1. Start - the shopper opens the My-Scan app or picks up a handheld scanner, and a basket is created for a specific store.
  2. Shopping - the shopper scans items as they pick them up, each scan is validated and priced in real time, and the basket total updates continuously.
  3. Checkout initiation - the shopper signals they're done (typically by scanning an End-Of-Trip barcode), which triggers checkout processing.
  4. Verification - depending on configured rules, the basket may go through one or more control steps (age verification, rescan) before it can be finalized.
  5. Payment & handover - once all controls pass, the basket is finalized and handed to a POS/SCO for payment, or paid directly on the shopper's device.

Throughout the trip, the basket moves through a well-defined state machine: NotInitialized → Starting → Started → Shopping → Finishing → Finished, with Cancelled possible from most states.

Customer Identification​

Shoppers can start a trip as either:

  • Registered - identified by a loyalty card/customer ID. The customer's profile is checked for blocked or inactive status before a basket is allowed to start, a blocked customer is rejected outright.
  • Anonymous - no customer identity is attached to the basket. Anonymous shoppers skip customer-level checks (blocking, trip-count limits) but are still subject to store-level and basket-level rules.

Customer data is resolved through a pluggable customer service - backed by the Customer Management Portal in cloud deployments, or the in-store Business Server for on-prem deployments.

Item Scanning​

Each scanned barcode is resolved to item data (description, price, promotions, age/security attributes) via the configured checkout engine or ItemData Service. Scanning handles several special cases:

  • Packaging - items sold in crates or multipacks may require the shopper to select a packaging type before the item can be added.
  • Ask-quantity items - some items (e.g. sold by weight or case) prompt the shopper to confirm a quantity.
  • Unknown items - barcodes that can't be resolved are still recorded as "unknown" items, flagged for review.

Removing or adjusting quantities follows the same real-time validation, and is only allowed while the basket is in the Shopping state.

Price Calculation​

Pricing is calculated continuously as items are scanned, using the store's configured price engine. The basket view exposes running totals: net price, number of items, quantity, and any promotions activated at basket or item level. Certain totals can be excluded from or included in the displayed net price depending on tenant/store configuration.

Age Verification​

Items with an age restriction are flagged during scanning with a required minimum age. At checkout, an AgeVerification control is created for all age-restricted items in the basket:

  • The control is sent to a store employee (attendant) for review, listing the flagged items and required age.
  • The employee approves or denies specific items.
  • Denied items are automatically removed from the basket, approved items are validated and the basket total is updated accordingly.
  • The basket cannot be finalized until all pending age verification controls are resolved.

Rescan​

A rescan or audit is a manual re-verification of some or all of a shopper's basket, performed by a store employee after the shopper finishes scanning. It exists to catch discrepancies before payment.

  • Determination - whether a rescan is triggered is decided by configurable rules, evaluated by the Basket Audit Evaluation Service.
  • Full vs. Partial - a Full Rescan re-verifies every item in the basket, a Partial Rescan re-verifies a subset.
  • Forced rescan - a rescan can also be forced, by an attendant/operator request, or when the shopper is using a store-owned device.
  • Execution - the rescan or audit itself runs on the Basket Audit Service (for cloud), independent of the Core Service. Results are reported back asynchronously and update the basket's control state - cancelling pending rescan controls, or marking them finished.

Payment​

Once all controls are resolved successfully, the basket becomes eligible for payment:

  • Direct mobile payment - the shopper can pay directly on their device via the Softpay app, the Core Service processes the payment, publishes a monitoring event, and completes the trip. See Integrate a Payment Provider for what's involved in supporting a new provider here.
  • Payment reversal - if a payment fails or needs to be reversed, the Core Service can request a reversal from the payment provider and update the basket's payment state accordingly.
  • Shopper assistance during payment - if the shopper needs help during checkout/payment, an assistance request can be raised to an attendant, this is automatically withdrawn once payment completes.
  • A basket cannot be downloaded by a POS while a payment is actively in progress, to avoid double-processing.

POS Handover​

When payment happens at a POS or self-checkout (SCO) instead of on the shopper's device:

  1. Download - the POS calls the download endpoint with the basket ID or resolves it by customer or by POS/workstation mapping, this returns the finalized ticket and removes the basket from active state on the Core Service.
  2. Upload - after payment, the POS uploads the transaction result back to My-Scan. This triggers a monitoring event, forwards the transaction to the Self-Service Analytics service for reporting, and cleans up any remaining POS/customer index mappings.

Abandoned Trips​

A shopping trip is considered abandoned if it sits inactive (no scans, no state change) for longer than a configurable inactivity timeout, evaluated per tenant. On a scheduled cleanup pass:

  • Baskets past the inactivity threshold, still in Started or Shopping state, are automatically cancelled.
  • A CANCELLED monitoring event is published for each cleaned-up basket.
  • If configured (EnableCustomerBlockingForAbandonedTrips), the associated customer is automatically blocked via the Customer Management Portal — see Operations: Customer Management Portal.
  • Cleanup is resilient: a failure blocking one customer or cancelling one basket does not stop cleanup of the remaining tenants/baskets.
  • A timeout of 0 disables abandoned-trip cleanup entirely for a tenant, a negative or missing value is treated as invalid configuration and logged as a warning.

Customer Blocking & Graylisting​

My-Scan supports blocking customers from starting new shopping trips, used both as a direct anti-fraud/loss-prevention measure and as a consequence of abandoned-trip behavior:

  • Blocking triggers - a customer can be blocked as a result of abandoned-trip cleanup, or through other loss-prevention signals evaluated by the rescan determination rules.
  • Effect - a blocked customer is rejected at basket-start time with CustomerCardBlocked, before any items can be scanned.
  • Where blocking happens - customer blocking is delegated to the Customer Management Portal or is a no-op for on-prem Business Server integrations, since that flow is centrally managed in the customer profile system.
  • Graylisting vs. blocking - graylisting is a softer signal that imposes rescans without preventing the shopper from starting a trip, blocking is a hard stop preventing any new basket from being started for that customer.