Business features

1. Shop wallet management

Credits wallet

Primary balance (credit_balance) shown on sidebar and dashboard.
Used to grant credits to players (deposit).
Every balance change dispatches shop-credit-balance-refresh event.

USD online balance

Separate USD wallet (online_balance_net).
Used to buy credits or withdraw crypto.
Separate ledger at /online-transactions.

Buy credits (`ShopCreditPurchaseModal`)

Two tabs:

Tab	Flow
Crypto	ZeroxProcessing static wallets (BTC, DOGE, LTC…), QR code, provider fees
Balance	Convert USD → credits per `cost_rate`

Cost rate: price ratio set by agent. credits = USD ÷ cost_rate.

flowchart LR
  A[Shop opens buy credits modal] --> B{Choose tab}
  B -->|Crypto| C[Select coin → static wallet QR]
  B -->|Balance| D[Enter USD → preview credits]
  D --> E[POST /shop/convert-balance-to-credits]
  C --> F[Player sends crypto → backend callback]

2. Player management

List (`/players`)

Search, pagination.
Sort by shop_assigned_at or name.
Create new player via form or ShopPlayerLinkByPhonePanel.

Create player

Method	API
Direct (phone/email)	`POST /shop/players`
OTP registration (legacy transfer)	`register-initiate` → `register-verify`

Player detail (`/players/:playerId`)

PlayerDetailPanel supports:

Action	API
Deposit credits	`POST /shop/players/:id/credits` (amount > 0)
Redeem credits	`POST /shop/players/:id/credits` (amount < 0)
Ban	`POST /shop/players/:id/ban` — period: 1d/3d/7d/30d/permanent
Unban	`POST /shop/players/:id/unban`
Reissue credentials	`POST /shop/players/:id/credentials/reissue`
Verify phone/email	`send-verification` → `verify`
Transaction history	`GET /shop/players/:id/transactions`

3. Withdrawals & Approval

Player withdrawals (`/withdrawals`)

Shop approves/rejects player withdrawal requests:

GET /shop/withdrawals/pending
  → Shop views list
  → POST /shop/withdrawals/:id/approve or /reject

Shop USD withdrawal (`/online-transactions`)

Crypto withdrawal flow from USD wallet:

sequenceDiagram
  participant S as Shop
  participant P as Shop Portal
  participant B as Backend

  S->>P: Open USD withdrawal form
  P->>B: GET /shop/online-balance/withdrawals/otp/eligibility
  P->>B: POST .../otp/send
  S->>P: Enter OTP
  P->>B: POST .../otp/verify
  S->>P: Select network, enter address
  P->>B: GET .../withdrawals/fee (preview)
  P->>B: POST /shop/online-balance/withdrawals

Supported networks: BTC, ETH, USDT (per config).
Limits: GET /shop/portal-withdrawal-limits.
Components: WithdrawOtpStep, WithdrawBlockedAlert from @kioskgaming/ui.

4. Cashier management

Shop Portal manages cashiers but does not perform counter transactions.

Action	Description
Create cashier	Username + password
Suspend	Temporarily lock account
Terminate	Permanently end account
View report	By period: daily/weekly/monthly
View shifts	Shift history

Cashier business details: Cashier Management.

warning

Cashier login on Shop Portal is rejected — portalLogin returning role: 'cashier' redirects to Cashier App.

5. Provider fees (`/provider-fees`)

Shop enables/disables payment methods by:

Provider (ZeroxProcessing, MEID, …)
Operation (deposit, withdrawal, transfer)
Method ID

Shows: gateway fee, system fee, network fee.

6. Fraud detection (`/fraud-indicators`)

Cashier tab

High redemptions
Cash discrepancies
Outside-shift transactions

Player tab

PlayerFraudIndicatorsPanel from @kioskgaming/ui
Detail + profit analysis + resolve

7. Kiosk domain & Marketing (`/kiosk-domain`)

Subdomain

Create/edit kiosk subdomain (e.g. myshop.kioskdomain.com).
API: GET/POST/PATCH /shop/kiosk-domain.

3 templates: NeonArcade, GoldPremium, DarkNeon.

Render HTML → export PNG via html-to-image.
QR code embeds kiosk subdomain.

8. Communication

Broadcasts (receive)

ShopNotificationBell polls every 2 minutes.
GET /shop/broadcasts → acknowledge via POST .../ack.

Broadcasts (send) — requires `can_delegate_popups`

POST /shop/broadcasts — send notification to players.

In-app popups

ShopInAppPopupGate — app-wide gate.
Modes: once / sticky_daily.
Shop sends popup: POST /shop/in-app-popups (requires delegate permission).

9. Settings & Security (`/settings`)

Setting	API	Notes
Cost rate	Display from profile	Set by agent, shop read-only
Low balance warning	`PATCH /shop/settings/low-balance-warning`	Minimum threshold $50
2FA login	`PATCH /shop/settings/two-factor`	Email/phone, must be verified first
Account verification	`send-otp` → `confirm`	`VerifyNowTrigger` in header

10. Legacy flows

Route	Status
`/transfer`	Redirect → `/players`
`/transfer/legacy`	Legacy flow: lookup phone + OTP registration
`/purchase`	Redirect → `/`

Implementation notes

Default port 3004 — avoids conflict with admin (3000) and agent (3003).
CORS: add dev domain to admin Domains or use DISABLE_CORS=true for local dev.
Payment return: backend redirects to /payment/success|cancelled|error with query transaction_id, status, message.
Zerox methods cache: useSupportedZeroxMethods caches 24h in localStorage.

1. Shop wallet management​

Credits wallet​

USD online balance​

Buy credits (ShopCreditPurchaseModal)​

2. Player management​

List (/players)​

Create player​

Player detail (/players/:playerId)​

3. Withdrawals & Approval​

Player withdrawals (/withdrawals)​

Shop USD withdrawal (/online-transactions)​

4. Cashier management​

5. Provider fees (/provider-fees)​

6. Fraud detection (/fraud-indicators)​

Cashier tab​

Player tab​

7. Kiosk domain & Marketing (/kiosk-domain)​

Subdomain​

Promo poster​

8. Communication​

Broadcasts (receive)​

Broadcasts (send) — requires can_delegate_popups​

In-app popups​

9. Settings & Security (/settings)​

10. Legacy flows​

Implementation notes​