MPAC Docs

Appearance

Merchant & Store Hierarchy ​

Part of: MPAC SmartPOS Cloud Platform - Product RequirementsVersion: 2.0 Last Updated: 2026-01-28

Overview ​

The Merchant & Store Hierarchy domain defines the multi-tenant organizational structure of the SmartPOS Cloud Platform. It establishes a three-tier hierarchy (PSP → Merchant → Store → Device) that enables scalable management of large fleets of SmartPOS terminals across multiple brands and locations. This structure supports white-label deployments, configurable payment settings, and hierarchical data aggregation for reporting and settlement.

Table of Contents ​

Multi-Tenant Structure ​

PSP (Payment Service Provider)
  └── Merchant (Business/Brand)
      └── Store (Physical Location)
          └── Device (SmartPOS Terminal)

PSP (Payment Service Provider) ​

Purpose: Top-level organization managing multiple merchant brands.

PSP Attributes ​

  • PSP ID
  • PSP Code (unique identifier)
  • Display Name
  • Contact Information
  • Status (active/inactive)
  • Created/Updated Timestamps

PSP Capabilities ​

  • Manage multiple merchant brands
  • Aggregated reporting across all merchants
  • White-label portal configuration
  • Global payment provider contracts

Merchant Entity ​

Purpose: Business or brand operating multiple store locations.

Merchant Attributes ​

  • Merchant ID
  • PSP ID (parent)
  • Merchant Code (unique within PSP)
  • Display Name
  • Business Name (legal)
  • Contact Email/Phone
  • Address
  • Tax ID/Business Registration
  • Payment Configuration (default for stores)
  • Logo/Branding
  • Status (active/inactive)

Merchant Settings ​

  • Default payment methods
  • Provider credentials (can be overridden at store level)
  • Receipt template
  • Invoice configuration
  • Settlement frequency
  • Terminal limit per store

API Endpoints ​

  • GET /merchants - List merchants (filtered by PSP)
  • GET /merchants/{id} - Merchant details
  • POST /merchants - Create merchant
  • PATCH /merchants/{id} - Update merchant
  • DELETE /merchants/{id} - Deactivate merchant

Store Entity ​

Purpose: Physical location where transactions occur.

Store Attributes ​

  • Store ID
  • Merchant ID (parent)
  • Store Code (unique within merchant)
  • Display Name
  • Address (street, city, postal code, country)
  • Contact Email/Phone
  • GPS Coordinates
  • Operating Hours
  • Payment Configuration (overrides merchant settings)
  • Printer Configuration
  • Receipt Settings
  • Status (active/inactive)

Store Settings ​

  • Enabled payment methods
  • Provider credentials (store-specific)
  • Printer IP/port configuration
  • Receipt delivery options
  • Staff roster
  • Table/POS terminal assignments
  • Tax rate configuration
  • Menu/product catalog (if applicable)

Store Operations ​

  • Daily settlement reconciliation
  • End-of-day reports
  • Device management
  • Staff management
  • Customer management

API Endpoints ​

  • GET /stores - List stores (filtered by merchant)
  • GET /stores/{id} - Store details
  • POST /stores - Create store
  • PATCH /stores/{id} - Update store
  • DELETE /stores/{id} - Deactivate store
  • GET /stores/{id}/devices - List devices in store
  • GET /stores/{id}/staff - List staff assigned to store

See Also ​

Related Domains:

  • IAM - Role-based access control scoped to hierarchy levels
  • Device Management - Device provisioning and store assignment
  • Order & Bill - Transaction processing within store context

Technical Implementation:

API Reference:

  • API Endpoints - Complete API specification for merchant and store management

Navigation: ← Previous: Device Management | ↑ Back to Domain Catalog | Next: Order & Bill →

MPAC — MP-Solution Advanced Cloud Service

MP Solution Inc.