HandyLife Wallet

Super-admin controls for the shared NGN wallet — feature flags, HITL queue, reconciliation.

Platform Wallet Stats

Total Wallets
—
across all eligible tenants
Active Wallets
—
status = active
Total Balance (₦)
—
sum across all wallets
Pending HITL
—
funding requests above threshold
Pending Funding
—
bank transfers awaiting proof
Frozen Wallets
—
admin-frozen wallets

Feature Flag Status

Wallet-to-Wallet Transfers

Allow users to send NGN between HandyLife wallets. Requires CBN approval + Phase W3 compliance hardening.

DISABLED

Wallet Withdrawals

Allow users to withdraw NGN to a linked bank account. Requires NIP integration + CBN limit gates.

DISABLED

Online Funding (Card / Paystack)

Allow users to top up via card payment. Requires Paystack virtual account integration (Phase W5).

DISABLED

MLA Commission Payout

Automatically credit MLA earners with pending commissions. Requires Phase W4 payout engine.

DISABLED

To toggle a flag: PATCH /platform-admin/wallets/feature-flags with body { "flag": "transfers", "enabled": true } — requires super-admin JWT.

HITL Funding Queue

Funding requests above the HITL threshold (default ₦100,000) require manual super-admin review. These were NOT auto-credited when the bank transfer was confirmed — action required.

Funding Request ID Wallet ID Amount (₦) Tenant Bank Transfer Order Created Actions
Loading HITL queue...

Wallet Admin API Reference

User Wallet Endpoints

POST
/wallet
Create wallet (idempotent). Requires payment_data NDPR consent.
GET
/wallet/balance
Balance, KYC tier, wallet status.
GET
/wallet/ledger
Paginated ledger history (cursor-based).
POST
/wallet/fund/bank-transfer
Initiate offline bank transfer funding. Creates hl_funding_request.
POST
/wallet/spend
Debit wallet. Records MLA commissions up referral chain.
GET
/wallet/mla-earnings
MLA commission history (pending, not yet paid out).

Super-Admin Endpoints

GET
/platform-admin/wallets/stats
Platform-wide wallet statistics + feature flag state.
GET
/platform-admin/wallets/hitl
List pending HITL funding requests (cursor-paginated).
PATCH
/platform-admin/wallets/feature-flags
Toggle transfers / withdrawals / online_funding / mla_payout.
POST
/platform-admin/wallets/funding/:id/confirm
Manually confirm HITL funding request. Credits the wallet.
POST
/platform-admin/wallets/funding/:id/reject
Reject a HITL funding request with reason.
POST
/platform-admin/wallets/:id/freeze
Freeze a wallet (blocks all debit operations). Cross-tenant.
GET
/platform-admin/wallets/reconciliation
Detect ledger drift (wallet balance ≠ ledger sum).

Phase Gate Summary

Phase W1 — Complete

Package, ledger, spend controls, migrations, routes, events, entitlements. 107 tests passing.

Phase W2 — Complete

Bank-transfer → auto-confirmFunding, HITL routing, MLA chain recording, NDPR consent gate, funding expiry CRON, this admin UI.

Phase W3 — Compliance Hardening

  • WF-031: CBN daily limit enforcement
  • WF-032: Balance cap enforcement
  • WF-034: Audit log on all mutations
  • WF-036: Governance doc

Phase W4 — MLA Payout Engine

  • WF-041: Payout CRON (feature-flag gated)
  • WF-042: creditMlaEarning() + idempotency
  • WF-043: ≥15 payout tests

Phase W5 — Vertical Integration

  • WF-051: Cooperative wallet payment
  • WF-052: Savings group wallet payment
  • WF-055: Paystack virtual account funding