--- title: "Digital Wallet & Financial Ledger Module Documentation" description: "Documentation for Wallet & Ledger" --- > **Module Code:** `billing/client/wallet-ledger` > **Route:** `/portal/wallet` > **Backend Service:** `clientService.ts` (`ring2all-billing-api`) > **Database Tables:** `wallets`, `transactions`, `customers` > **Brand Purity:** 100% White-Label Compliant (Ring2All Billing) --- ## Table of Contents 1. [Executive Summary & Financial Control](#1-executive-summary--financial-control) 2. [Technical Architecture & Dual-Entry Ledger Pipeline](#2-technical-architecture--dual-entry-ledger-pipeline) 3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities) 4. [Visual Interface & Screen Breakdown](#4-visual-interface--screen-breakdown) 5. [Prepaid Balance, Credit Line & Emergency Floor](#5-prepaid-balance-credit-line--emergency-floor) 6. [Double-Entry Transaction Record Specification](#6-double-entry-transaction-record-specification) 7. [Database Schema & Data Dictionary](#7-database-schema--data-dictionary) 8. [Diagnostic CLI & Operational Playbooks](#8-diagnostic-cli--operational-playbooks) 9. [Domain Glossary](#9-domain-glossary) --- ## 1. Executive Summary & Financial Control The **Digital Wallet & Financial Ledger** module provides corporate clients with a centralized financial control center for prepaid telephony funds, postpaid credit limit extensions, and an immutable, double-entry audit trail of every financial transaction. ``` +-------------------------------------------------------------------------------+ | COMMERCIAL & OPERATIONAL IMPACT | +-------------------------------------------------------------------------------+ | • Zero Dropped Calls: Combines live prepaid balance with an emergency credit | | limit to prevent sudden call termination during high-volume periods. | | • Instant Auditability: Every top-up, subscription charge, and outbound usage | | debit is permanently recorded with before-and-after balance snapshots. | | • Autonomous Refills: Integrated quick top-up buttons allow immediate funding | | via vaulted Stripe payment methods. | | • Multi-Currency Support: Real-time ISO currency precision down to 4 decimals.| +-------------------------------------------------------------------------------+ ``` --- ## 2. Technical Architecture & Dual-Entry Ledger Pipeline When telephony calls or monthly recurring charges occur, the billing engine performs atomic balance adjustments and commits immutable transaction rows: ``` ┌────────────────────────────────────────────────────────────────────────┐ │ Financial Event Dispatcher │ │ • Customer Fund Top-Up (Stripe PaymentIntent Webhook) │ │ • Monthly Subscription Sweep (Cron Engine) │ │ • CDR Toll Rating Debit (Online Charging System) │ └───────────────────────────────────┬────────────────────────────────────┘ │ ▼ BEGIN TRANSACTION (Serializable) ┌────────────────────────────────────────────────────────────────────────┐ │ Atomic Ledger Transaction Processor │ │ │ │ 1. SELECT balance, credit_limit FROM wallets WHERE customer_id = $id │ │ 2. Verify: (CurrentBalance + CreditLimit - DebitAmount) >= 0.00 │ │ 3. UPDATE wallets SET balance = balance + Delta, updated_at = NOW() │ │ 4. INSERT INTO transactions (wallet_id, type, amount, balance_after) │ └───────────────────────────────────┬────────────────────────────────────┘ │ COMMIT ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ Real-Time Balance Cache Sync │ │ Kamailio SBC In-Memory Cache (htable: cust_balance) │ │ Portal UI WebSocket / Polling Refresh (WalletPage.tsx) │ └────────────────────────────────────────────────────────────────────────┘ ``` --- ## 3. 🎯 User Roles & Key Capabilities Access to ledger records and fund operations is governed by enterprise authorization roles: | User Role | Access Level | Primary Operational Capabilities | | :--- | :--- | :--- | | **Corporate Treasurer / Financial Officer** | Full Financial | Monitors corporate balance, executes one-click top-ups, audits transaction statements. | | **Enterprise Telecom Manager** | Operational Monitoring | Verifies available calling credit to ensure trunk availability; configures low-balance email alerts. | | **Staff Accountant / Bookkeeper** | Reconciliation | Downloads ledger CSVs to reconcile recurring subscription charges against bank merchant statements. | | **Customer Service Representative** | View Only | Reviews past customer deposits and refunds to answer billing inquiries. | --- ## 4. Visual Interface & Screen Breakdown ### 4.1 Digital Wallet & Transaction Ledger Overview The wallet view presents real-time fund metrics alongside an itemized ledger table: ![Digital Wallet & Transaction Ledger Overview](/screenshots/billing/client/wallet/wallet-ledger.png) * **Current Balance Card:** Prominently displays the total available prepaid funds ($145.50) in USD. * **Credit Limit Card:** Reflects approved overdraft headroom ($50.00) available before outbound trunk shutdown. * **Effective Spending Power:** Combined liquidity available for active concurrent calls. * **Quick Top-Up Actions:** One-click deposit triggers ($25, $50, $100, $250, or custom amount). * **Transaction Ledger Table:** Detailed itemization displaying date, reference ID, transaction type (`topup`, `recurring_charge`, `usage_debit`), gross amount, and resulting balance. --- ## 5. Prepaid Balance, Credit Line & Emergency Floor The Ring2All Billing core enforces a multi-tier balance protection protocol: 1. **Prepaid Tier:** Active calls first consume the customer's prepaid balance (`wallets.balance`). 2. **Credit Line Tier:** If the balance reaches `$0.00`, calls continue uninterrupted against the authorized `credit_limit`. 3. **Emergency Floor (Hard Cutoff):** When total debt exceeds `credit_limit`, the SBC rejects new outbound call attempts with `SIP/2.0 402 Payment Required`. --- ## 6. Double-Entry Transaction Record Specification Every row in the `transactions` ledger contains deterministic accounting data: | Transaction Field | Example Value | Description | | :--- | :--- | :--- | | **Reference ID** | `TX-891024` | Unique alphanumeric tracking identifier. | | **Type** | `topup` | Transaction category (`topup`, `subscription`, `usage`, `refund`). | | **Amount** | `+$100.00` | Net credit (green) or debit (red) applied to wallet. | | **Balance After** | `$145.50` | Exact wallet balance snapshot immediately following the transaction. | | **Status** | `completed` | Processing state (`pending`, `completed`, `failed`, `reversed`). | --- ## 7. Database Schema & Data Dictionary ### Table: `public.wallets` ```sql CREATE TABLE public.wallets ( id BIGSERIAL PRIMARY KEY, uuid UUID NOT NULL DEFAULT gen_random_uuid(), customer_id BIGINT NOT NULL UNIQUE REFERENCES customers(id) ON DELETE CASCADE, currency VARCHAR(3) NOT NULL DEFAULT 'USD', balance NUMERIC(12,4) NOT NULL DEFAULT 0.0000, credit_limit NUMERIC(12,4) NOT NULL DEFAULT 0.0000, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); ``` ### Table: `public.transactions` ```sql CREATE TABLE public.transactions ( id BIGSERIAL PRIMARY KEY, uuid UUID NOT NULL DEFAULT gen_random_uuid(), customer_id BIGINT NOT NULL REFERENCES customers(id) ON DELETE CASCADE, wallet_id BIGINT NOT NULL REFERENCES wallets(id) ON DELETE CASCADE, type VARCHAR(30) NOT NULL, amount NUMERIC(12,4) NOT NULL, balance_after NUMERIC(12,4) NOT NULL, currency VARCHAR(3) NOT NULL DEFAULT 'USD', description TEXT, reference_id VARCHAR(100), status VARCHAR(20) NOT NULL DEFAULT 'completed', created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); -- Audit query index CREATE INDEX idx_transactions_customer_time ON transactions (customer_id, created_at DESC); ``` --- ## 8. Diagnostic CLI & Operational Playbooks ### Verify Customer Wallet & Ledger via CLI ```bash su - postgres -c "psql -d ss_billing -c \" SELECT w.balance, w.credit_limit, t.type, t.amount, t.balance_after, t.created_at FROM wallets w JOIN transactions t ON t.wallet_id = w.id WHERE w.customer_id = 5 ORDER BY t.created_at DESC; \"" ``` --- ## 9. Domain Glossary * **Double-Entry Ledger:** Bookkeeping architecture where every balance mutation records both credit/debit amount and resultant state. * **Effective Spending Power:** Sum of available positive balance plus approved credit limit. * **Credit Limit:** Maximum allowed negative balance before telecom services are suspended.