User manual

1. Introduction

SammPOS is a point-of-sale and business-management application. Its modules include product/catalog management, cashier sales, customers, suppliers, purchases, stock operations, accounting, reports, staff permissions, and operational settings.

SammPOS also includes a license client that communicates with the separate Validator service during installation and license rechecks. That connection supports licensing; it is not part of the cashier or stock workflow.

2. Getting started

Install SammPOS

The installer exposes welcome/language, requirements, optional license, database, database migration, administrator, and demo-mode steps. License enforcement and rechecks are controlled by installation configuration. Once installed, staff sign in through the SammPOS login page.

Set up your workspace

1. Complete the installation and create the first administrator account.
2. Configure the business, store/location, cashier behavior, and payment methods that apply to your operation.
3. Set up catalog values, products, customers, and suppliers.
4. Assign staff roles and permissions before staff begin using checkout and management screens.

3. Dashboard

SammPOS provides a dashboard and report views for sales and operations. The information available depends on the selected store, current date range, permissions, and recorded activity. Use the navigation to open the module behind a summary or continue with the task assigned to your role.

4. Products

In SammPOS, products are maintained alongside categories, brands, units, and related catalog data. Product screens provide listing, search, create/edit, active-state controls, and product export. The routes also include product import preview/commit, bulk image matching, and label-sheet generation.

1. Set up the catalog values your product form requires, such as categories and units.
2. Create a product or use the import workflow: download its template, upload a filled file for preview, review validation feedback, then commit the import.
3. Maintain price and product details on the edit screen. Use the product list to search and export records.
4. Where a product is tracked by stock, use the inventory screens for quantity changes rather than treating a sale as a manual adjustment.

The installed configuration and permissions determine which catalog actions are available.

5. Sales and POS

SammPOS provides a sales list and a dedicated cashier interface. The cashier routes support catalog synchronization, product search and scanning, customer lookup/quick add, held carts, recent sales, shift operations, terminal selection, payment sessions, and receipt reprinting. A self-ordering kiosk surface is also present.

1. Open the cashier and select or scan items into the current sale.
2. Choose an existing customer or add one from the cashier if permitted.
3. Review the quote/total and apply any allowed discount. Some discounts require manager approval according to the configured threshold.
4. Complete checkout with an available configured payment method. If enabled, the cashier can create a payment session for customer QR/gateway checkout.
5. Use the sales list or receipt action to review a completed transaction.

Held carts can be resumed or voided from the cashier. Shift and terminal requirements depend on the store’s cashier settings. Sale returns/refunds are available through the sale/refund workflow subject to permissions and payment state.

6. Customers

Customer management includes customer records, search, create/edit, activation, import/export, customer groups, and customer statements. The application also exposes loyalty settings and manual loyalty-point adjustments where authorized.

From a customer record, review related sales and balances as displayed by the application. Customer payments can be recorded through the relevant payment workflow; statement exports and messaging options are available only when configured.

7. Suppliers

Supplier records support the purchasing workflow. SammPOS includes supplier lists and create/edit actions, supplier payments, and a top-suppliers report. Supplier payment statements and WhatsApp delivery are present when the corresponding integration is configured.

Keep supplier details current so purchase records and outgoing balances can be associated with the correct supplier.

8. Purchases

Use purchase records to enter stock received from suppliers and related costs/payments. Purchase routes include list/detail and payment operations, and the application has purchase markup/pricing settings. Supplier advance posting is also handled by the purchase-payment subsystem.

1. Select the supplier and add the products and quantities being received.
2. Review the purchase totals, applicable costs or configured markup, and payment amount.
3. Save/receive the purchase using the available workflow. Stock changes are recorded through the purchase process.
4. Review the purchase and any associated supplier payment from their respective lists.

Field names and whether a purchase can be edited or voided depend on its current status and permissions.

9. Inventory and stock

SammPOS provides stock levels, stock movements, stock adjustments, stock takes, and stock transfers. A stock take can be prepared, reviewed, and posted; adjustment records capture deliberate quantity changes; transfers have dispatch, receive, and cancellation actions. These operations can be store/location scoped.

Choosing the right stock workflow

• Stock level or movement: inspect the current quantity or its recorded changes.
• Adjustment: record a known increase/decrease and its adjustment reason.
• Stock take: compare counted quantities with the system and post the reviewed count.
• Transfer: move stock between configured locations, then record dispatch and receipt.

Low-stock and oversold reports are available. Import tools exist for stock takes and adjustments. Review import previews before committing changes.

10. Payments

SammPOS records payment methods and supports cashier payment flows, customer and supplier payments, and configured payment gateway checkout. Gateway routes currently exist for Stripe, Razorpay, Paystack, Flutterwave, and Mercado Pago; an individual provider is usable only when configured for the installation. Static UPI and QR payment-session routes are also present.

Check the transaction or related sale/purchase/customer/supplier record for the state available in the current workflow. Gateway callbacks and webhooks update payment state; do not treat a customer’s browser return alone as proof that a gateway has settled a payment.

Validator separately records subscription payment transactions and supports SSLCommerz and bKash for its subscription-payment flow. Its default gateway is selected by an administrator. Paid confirmation updates renewal state through the callback processing.

11. Reports

SammPOS includes a reports hub. The routes currently expose the following reports; filtering and export options vary by report. Open a report to see its current filters and use its export action where available.

Accounting reports are based on posted ledger activity. A report can be empty when no matching records exist for its date range, store, or other selected filters.

12. Users, staff, and roles

SammPOS has user and role management with permission-controlled routes and actions. Assign each staff member only the access needed for their duties. A user’s visible navigation and ability to create, edit, approve, export, or post records follow the permissions assigned to that user/role. Some sensitive changes require a super-admin or an additional manager approval.

Validator’s administrator login is separate: users must have an active account with the administrator role. Validator customers do not sign in to the admin workspace.

13. Settings

SammPOS settings are split into focused screens. The installed build contains settings for cashier behavior, scales, security, custom scripts, locations, loyalty, license status, pricing/markup, number formats, email, WhatsApp, backups, restore, updates, and system health. Other business and payment-method options appear according to the enabled application modules.

• License: view current license state, recheck it, renew the subscription, or manage the current-domain registration when permitted.
• Cashier and locations: configure checkout behavior and the store/location context.
• Pricing and numbering: configure purchase markup behavior and business document numbering.
• Email and WhatsApp: configure delivery connections and test them before relying on message sending.
• Backup and restore: run/download backups and use the restore flow only after reviewing its validation step.
• Updates and system health: check update availability and inspect system status using the provided tools.

Changes are permission-gated. Some settings depend on deployment environment or license status and may not be available in demo mode.

14. Validator integration

What is the Validator?

Validator stores customers, subscription plans, subscriptions, projects, project credentials, validation logs, and payment transactions. A validation request checks that a project is active and belongs to an active customer with an active plan and an in-date active subscription. Domain validation is enabled unless the administrator turns it off in system settings.

How SammPOS uses it

SammPOS includes an installer license step and a license client. The client submits a purchase/license code and installation URL to its configured Validator URL, and stores the validated license state for later checks. Its renewal flow requests a checkout URL and checks the invoice status; after confirmed payment, SammPOS reactivates the configured license key.

Project setup and credentials

A Validator administrator creates a customer, plan, subscription, and project in the administration workspace. Project creation issues a project code and API key; the project also has a separate secret whose hash is stored. The validation handlers use the project code and, when supplied, check X-API-Key (or api_key) against the project API key. The secret is not an API validation key.

Validation API

The legacy endpoint accepts GET or POST at /api/validate. SammPOS is configured to POST there. Validator also exposes POST /api/v1/projects/validate, which returns a smaller versioned response. Send an explicit registered domain; the incoming domain must match the project domain while domain validation is enabled.

curl -X POST "https://validator.example/api/v1/projects/validate" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: PROJECT_API_KEY" \
  -d '{
    "project_code": "PROJECT_CODE",
    "domain_url": "https://your-installed-domain.example"
  }'

Replace the example host and credential placeholders with values from the actual installation. Do not publish the real API key.

Recorded rejection reasons include not_found, invalid, unknown_product, token_mismatch, blacklisted, and domain_already_registered. These are reason values, not separate HTTP status codes.

Renewal checkout API

For eligible expired projects, POST to /api/v1/projects/renewal-checkout with the project API key and project code. The selected default payment gateway must be configured. A successful JSON response contains the payment checkout URL; the API does not mark a renewal paid until the gateway confirms it.

curl -X POST "https://validator.example/api/v1/projects/renewal-checkout" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: PROJECT_API_KEY" \
  -d '{"project_code":"PROJECT_CODE"}'

After checkout, check /api/v1/projects/renewal-status using the returned invoice or transaction ID and project credentials. The SammPOS renewal screen performs the corresponding check and activates the configured license key only when the status is successful.

15. Validation troubleshooting

All failed attempts are recorded when the validation service can write to its database. Administrators can inspect Validation Logs for the request domain, time, IP, status, and stored failure reason. A network or server error before a request reaches Validator may not create a log.

16. Common questions

How do I get into the Validator admin workspace?

Use the administrator login page. Validator customers are records managed by administrators and do not have customer portal credentials in the current application.

Why did a project activation get rejected?

Validator requires an active subscription with an active plan and an active customer account before activating a project. Check all three records.

What happens after a subscription expires?

A project cannot pass the active subscription check. An eligible expired project can request renewal checkout through the API if the customer, plan, project status, gateway, and payment configuration permit it.

Why is the domain in my validation log different?

The service reads a domain from request fields such as domain or domain_url, then host headers as a fallback. Send the intended project domain explicitly and inspect reverse-proxy host handling.

Where do I find SammPOS reports and settings?

Sign in to SammPOS and use the navigation links for Reports or Settings. Some sections are hidden unless the current role has the required permission.

How do I contact support?

Use the support channel supplied by the administrator or the SammPOS vendor. This Validator installation does not expose a public contact form.