MooChedda Merchant Portal

The merchant portal is the operational front end for creating a store, managing products, running a desktop point-of-sale checkout, generating payment QR codes, reviewing order history, and delegating staff access while routing all payments to the owner wallet.

Where this fits Use merchant.html to operate the store. Use wallet.html for customer payment and wallet management.

What the merchant app does

The merchant experience is built around a registered store profile tied to a MooChedda wallet. Once connected, the app loads the store, products, order history, accepted tokens, and staff access. From there, the merchant can run checkout entirely inside the browser and present a QR code directly to the customer.

Core operating model

The owner wallet is the canonical merchant identity. Staff wallets may manage products and process sales, but invoice proceeds are always directed to the owner wallet address. The UI reflects this by showing staff mode banners, owner-only staff controls, and owner-linked order history.

Getting Started

The merchant portal supports a short setup path:

1

Connect or import a wallet

Load a wallet JSON file or import using a private key or mnemonic phrase. The connected wallet is persisted locally in the browser.

2

Register the store

If the wallet is not already an owner or staff wallet, the merchant can create a store name and optional logo to establish the merchant profile.

3

Add products

Create catalog items with name, description, token, price, and optional product image.

4

Run checkout and charge

Use the checkout screen as the merchant POS, build a cart, click Charge, and present the QR code to the customer.

Wallet setup options The merchant wallet modal supports JSON upload, private key import, mnemonic import, disconnect, and owner-only store profile updates.

Owner and Staff Roles

Role	What it can do	Payment destination
Owner	Create the store, edit store profile, manage products, process checkout, review orders, add or remove staff.	Owner wallet
Staff	Manage products and process payments on behalf of the store.	Owner wallet

When a staff wallet logs in, the portal switches into staff mode and clearly states that payments still route to the owner wallet. Staff users do not receive the staff-management tab.

Feature Summary

Merchant wallet connection using JSON file, private key, or mnemonic.
Store registration with name and optional logo.
Owner-only store profile editing from the wallet setup modal.
Product creation, editing, deletion, and image upload.
Desktop POS layout with all items on the left and current cart on the right.
Tax rate input, order note, accepted token chips, and live total calculation.
Charge action that creates an invoice and displays a payment QR.
Automatic polling of invoice payment status with paid and expired states.
Order history with search, detail view, and QR reopening for pending invoices.
Owner-managed staff list with add, remove, and QR wallet scanning.
Persistent dark and light theme toggle for the merchant interface.

Product Management

Products are managed from the Products tab. Each product supports a name, optional description, token, price, and optional product photo. The same product list is used by both catalog management and checkout.

Product fields

Field	Required	Description
name	Required	Customer-facing product name.
price	Required	Numeric unit price in the selected product token.
token	Optional	Defaults to `CHEDDA`; additional symbols are loaded from the token API.
desc	Optional	Short helper text shown in the catalog.
photo	Optional	Client-side processed product image displayed in both product and cart views.

Shared catalog Any product added or edited becomes immediately available in checkout because the app re-renders both the product list and the picker from the same merchant profile data.

Desktop POS Checkout

On desktop screens, checkout is presented as a POS layout. The left side shows the full product list. The right side shows the active cart, tax and note inputs, token acceptance settings, totals, and the final Charge action.

Checkout behavior

Click any item on the left to add it to the order.
Adjust quantity in the right-hand cart with plus and minus controls.
Set a tax percentage and optional order note.
Select one or more accepted payment tokens using token chips.
Review live subtotal, tax, and total before charging.

// Total calculation used by checkout
// subtotal = sum(item.price × item.qty)
// tax      = subtotal × (taxRate / 100)
// total    = subtotal + tax

Token handling The first active accepted token is treated as the base display token in the cart totals and invoice summary.

QR Charging and Payment Flow

Clicking Charge creates an invoice on the server and opens a full payment modal. The modal displays a QR code, the invoice URI, order summary, current status, and a New QR action for regeneration.

1

Merchant builds the cart

The app converts cart entries into invoice line items using name, unit price, and quantity.

2

Invoice is created

The merchant app calls POST /invoice/create using the owner wallet as the payment destination.

3

QR is shown to the customer

The merchant presents the generated QR to the customer for scanning and payment in the MooChedda wallet.

4

Status is polled until paid or expired

The portal polls invoice status every few seconds and updates the modal state to waiting, paid, or expired.

// QR payload used in the merchant modal
moochedda:invoice/INV-1710000000000-abc123

Pending invoice recovery If the modal is closed while the invoice is still pending, the merchant can reopen it later from order detail using Show QR.

Orders and Order Detail

The Orders tab shows merchant invoices sorted newest first. Orders can be searched by invoice ID, status, merchant name, note, or item name. Selecting an order opens a detailed view with line items, totals, timestamps, note, accepted tokens, and current status.

Order detail capabilities

Review subtotal, tax, and total after invoice creation.
See whether the order is pending, paid, or expired.
Inspect invoice metadata such as created time and paid time.
Reopen the QR modal for pending invoices.

Staff Access

Owners can manage staff from the Staff Access tab. Staff entries can include a wallet address and an optional description, such as role or location. The portal also includes a QR scanner so a staff wallet address can be captured directly from a wallet QR code.

Staff workflow

Add staff by entering an address manually or scanning a QR code.
Store an optional description for easier operational identification.
Remove staff access at any time from the staff list.
Allow staff to process sales without redirecting funds away from the owner wallet.

Light and Dark Theme

The merchant portal now supports both dark and light mode. A header toggle switches theme immediately, and the current selection is persisted locally in the browser using merchant_theme.

Area	Theme-aware behavior
Header and cards	All main interface surfaces follow the active theme tokens.
Bottom navigation	The floating desktop nav and mobile nav use the matching themed surface.
Modals	Wallet setup, product, invoice, staff QR, and order detail modals all switch with the active theme.
Persistence	Theme preference is saved and restored on future visits.

Merchant /merchant/register, /merchant/:address, /merchant/by-staff/:address Store registration and profile loading

The merchant app uses these endpoints to determine whether a connected wallet is an owner, staff member, or a new merchant needing registration.

Action	Method	Description
Create merchant	`POST`	Register a new merchant profile with owner wallet, name, and optional logo.
Load owner profile	`GET`	Fetch a merchant profile directly by owner address.
Load staff profile	`GET`	Resolve a staff wallet back to its parent merchant profile.
Update store profile	`PUT`	Owner-only update of merchant name and logo.

Products /merchant/:address/product and /merchant/:address/product/:productId Product CRUD

These endpoints back the merchant product editor and keep the POS catalog in sync.

Method	Use
`POST`	Create a product for the merchant catalog.
`PUT`	Edit an existing product.
`DELETE`	Remove a product and prevent future checkout use.

Invoices /invoice/create, /invoice/:id, /invoice/:id/status, /merchant/:address/orders Checkout, QR generation, payment polling, and order history

The merchant portal relies on invoice endpoints for live checkout and uses the orders endpoint as its order-history source.

Endpoint	Purpose
`POST /invoice/create`	Create a checkout invoice from cart items, tax rate, accepted tokens, and note.
`GET /invoice/:id`	Reopen full invoice details, including pending QR sessions.
`GET /invoice/:id/status`	Poll invoice status until the payment is complete or expires.
`GET /merchant/:address/orders`	Load merchant order history for the Orders tab.

Invoice request body used by the portal

{
  "merchantAddress": "OWNER_WALLET_ADDRESS",
  "merchantName":    "My Store",
  "items": [
    { "name": "Coffee", "price": 4.50, "quantity": 2 }
  ],
  "taxRate": 0.075,
  "acceptedTokens": ["CHEDDA", "USDT"],
  "note": "Table 12"
}

Staff /merchant/:address/staff and /merchant/:address/staff/:staffAddress Owner-managed staff list

These endpoints allow owners to grant or revoke staff access without changing the store owner wallet.

Method	Description
`POST`	Add a staff wallet and optional description.
`DELETE`	Remove a staff wallet from the merchant profile.

Operational Notes

Address format matters MooChedda merchant and staff wallets use MooChedda wallet addresses, not Ethereum-style 0x addresses.

Token list is dynamic The accepted-token chips and product token list are populated from the token API where available, with CHEDDA always present as the default fallback.

Desktop and mobile The checkout screen adapts responsively. Desktop uses the two-column POS layout, while mobile keeps a stacked workflow optimized for smaller screens.

Example Files

The Merchant-Examples folder includes sample integration assets you can use alongside the merchant portal.

payment-example.html for invoice-based website checkout.
WEBSITE_PAYMENTS_DOCS.html for website payment API integration using invoice creation, wallet redirect, QR scanning, and status confirmation.
DOCS.html for merchant operations and endpoint reference.

MooChedda Merchant Portal

What the merchant app does

Core operating model

Getting Started

Owner and Staff Roles

Feature Summary

Product Management

Product fields

Desktop POS Checkout

Checkout behavior

QR Charging and Payment Flow

Orders and Order Detail

Order detail capabilities

Staff Access

Staff workflow

Light and Dark Theme

API Endpoints Used by the Merchant Portal

Invoice request body used by the portal

Operational Notes

Example Files