Admin Wallet Flows

This guide documents the wallet flows available to club staff and operations teams. It covers the primary SCL Admin UI and the legacy MCA admin UI, with data sources so audit and analytics can be validated.

Quick Reference

Task	Location	Role Required
View all wallets	SCL Admin → Wallets	wallet:read
Bulk credit/debit	SCL Admin → Wallets → Bulk Adjust	wallet:adjust
View wallet audit	SCL Admin → Wallets → [wallet] → Audit	wallet:read
Manage auto top-up	SCL Admin → Wallets → [wallet] → Auto Top-Up	wallet:manage
Suspend/reactivate	SCL Admin → Wallets → [wallet] → Status	wallet:manage
Retry notifications	SCL Admin → Wallet Outbox	wallet:outbox
Top up (legacy)	MCA Admin → Member Wallets	mca:wallet:topup
Transfer funds	MCA Admin → Member Wallets	mca:wallet:transfer
Reverse transaction	MCA Admin → Member Wallets	mca:wallet:reverse

SCL Admin (Primary)

1) Wallets Dashboard (/wallets)

Purpose: View wallets, filter by club, inspect analytics, and perform bulk adjustments.

Primary data sources

• GET /api/admin/wallets (list/search/filter)
• GET /api/admin/wallets/analytics (totals, spend, cohorts, retention, passes, merchants)

What staff can do

• Search by member name/email.
• Filter by club (when multiple clubs exist in the tenant).
• Open a member wallet audit record.
• Run bulk adjustments (credit/debit) with a batch reference.

Bulk adjust flow

1. Select wallets or upload a CSV.
2. Choose credit or debit direction and enter a reference.
3. Submit adjustment → system posts a wallet transaction and a double-entry journal.
4. A wallet.transaction.posted outbox event is published.
5. Capture the batchId for audit lookup and notification retries.

2) Wallet Audit (/wallets/:walletId/audit)

Purpose: Inspect the ledger-backed audit trail for a specific wallet.

Primary data sources

• GET /api/admin/wallets/:walletId/summary
• GET /api/admin/wallets/:walletId/transactions
• GET /api/admin/wallets/:walletId/journal-entries
• GET /api/admin/wallets/:walletId/status-events
• GET /api/admin/wallets/:walletId/auto-topup
• GET /api/admin/wallets/:walletId/categories
• GET /api/admin/wallets/:walletId/category-rules

What staff can do

• Review wallet balance, currency, and status.
• Inspect transactions and open the linked journal entry (double-entry audit).
• Filter by batchId for bulk adjustments.
• Create or assign spending categories.
• Pause/resume/cancel auto top-up for the wallet.
• Review status history timeline.

Realtime refresh

• The audit page listens to GET /api/admin/wallets/:walletId/events (SSE).
• New events trigger re-fetch of summary, transactions, journals, status events, and auto top-up.

3) Wallet Outbox (/wallet-outbox)

Purpose: Monitor delivery of wallet events (notifications, integrations) and retry failures.

Primary data sources

• GET /api/admin/wallet-outbox (filters: status, eventType, search, batchId)
• POST /api/admin/wallet-outbox/:id/retry
• POST /api/admin/wallet-outbox/retry (bulk retry)

What staff can do

• Filter by status (pending, processing, failed, dead-letter, succeeded).
• Filter by event type or batchId.
• Retry individual or multiple outbox entries.

4) Wallet Analytics (Dashboard Panel)

Metrics included

• Wallet totals by status.
• Spend summary by currency, type, category, trend.
• Merchant rollups (based on transaction metadata).
• Cohorts by club and tier.
• Retention curves.
• Pass installs/events and provider breakdown.

Primary data sources

• wallet-data: WalletAccount, WalletTransaction, WalletJournalEntry, WalletSpendingCategory, WalletPass
• scl-data: Member, MemberClub, MembershipTier

5) Account Status Management

Wallet statuses

• ACTIVE - Normal operation, can top up and spend
• SUSPENDED - Temporarily blocked (e.g., payment failure, fraud review)
• CLOSED - Permanently closed, balance refunded or transferred

Suspend a wallet

1. Open the wallet audit page.
2. Click Status → Suspend.
3. Enter a reason (required for audit trail).
4. Confirm suspension → creates WalletAccountStatusEvent.
5. Member cannot spend or top up until reactivated.

Reactivate a suspended wallet

1. Open the wallet audit page.
2. Click Status → Reactivate.
3. Enter resolution notes.
4. Confirm → wallet returns to ACTIVE.

Close a wallet

1. Ensure balance is zero (refund or transfer remaining funds first).
2. Open the wallet audit page.
3. Click Status → Close.
4. Enter closure reason.
5. Confirm → wallet is permanently closed.

Note: Closed wallets cannot be reopened. A new wallet must be created if the member returns.

MCA Admin (Legacy)

MCA still provides operational actions that have not been fully migrated into SCL Admin:

Member Wallets (MCA)

• Top up a wallet (GraphQL mutation).
• Transfer funds between members.
• Reverse a transaction with a reason (admin action).

Use MCA for reversals until the reversal flow is exposed in SCL Admin.

Audit Trail & Double-Entry Ledger

Every wallet transaction posts a matching journal entry to enforce double-entry accounting. The Wallet Audit page shows the link between transactions and their ledger entries so operations can reconcile balance discrepancies.

Troubleshooting Quick Checks

• Missing wallet: verify the member has a walletAccountId and is linked to the correct tenant/club.
• Balance mismatch: compare transaction totals with journal entries; see docs/wallet/internal/runbooks/balance-discrepancy.md.
• Notification not delivered: check Wallet Outbox for failed/dead-letter entries and retry.