---
title: "Add Funds & Prepaid Wallet Module Documentation"
description: "Documentation for Add Funds & Wallet"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Prepaid Digital Wallet & Credit Limits](#4-prepaid-digital-wallet--credit-limits)
5. [Instant Stripe Top-Up Modal, Presets & Payment Processing](#5-instant-stripe-top-up-modal-presets--payment-processing)
6. [Financial Ledger & Transaction Audit Trail](#6-financial-ledger--transaction-audit-trail)
7. [Troubleshooting & Verification](#7-troubleshooting--verification)
8. [Glossary](#8-glossary)

---

## 1. Module Overview (Technical)

The **Add Funds & Prepaid Wallet** module (`WalletPage.tsx`, `TopupModal.tsx`, and `clientService.ts`) manages balance top-ups, credit reserves, automated replenishment triggers, and double-entry transaction ledgers in the **Ring2All Billing Client Portal**. It safeguards carrier margins by maintaining strict prepaid debit controls and preventing unauthorized PSTN traffic when account balances are exhausted.

```mermaid
sequenceDiagram
    autonumber
    actor Client as Customer Portal
    participant API as Ring2All Billing API
    participant Stripe as Stripe Payment Gateway
    participant DB as PostgreSQL (ss_billing)
    participant OCS as Online Charging System (OCS)

    Client->>API: POST /api/client/wallet/topup { amount: 50.00, currency: 'usd' }
    API->>Stripe: Create & Confirm PaymentIntent (Saved Card / Vault)
    Stripe-->>API: 200 OK (PaymentIntent pi_3N9... Succeeded)

    critical Atomic Wallet Balance Update
        API->>DB: UPDATE wallets SET balance = balance + 50.00 WHERE customer_id = :id
        API->>DB: INSERT INTO transactions (customer_id, wallet_id, amount, balance_after, type='topup')
        API->>OCS: Update In-Memory Balance Cache (Redis / OCS Worker)
    end

    API-->>Client: 201 Created (Wallet Credited Instantly)
    Client->>Client: Refresh Wallet KPI & Ledger Table ($145.50 -> $195.50)
```

### Key Technical Capabilities
* **Atomic Balance Mutations:** Utilizes PostgreSQL ACID transactions to ensure balance increments and ledger entries commit simultaneously without rounding discrepancies.
* **Low-Latency OCS Cache Synchronization:** Instantly updates real-time rating workers, immediately lifting call barring or low-balance routing restrictions upon payment receipt.
* **PCI-DSS Compliant Tokenization:** Integrates with Stripe payment elements and customer vault IDs, ensuring credit card numbers never touch Ring2All servers.

---

## 2. Module Overview (Commercial & Business Value)

* **Zero Credit Risk for Carriers:** Enforcing prepaid wallet top-ups eliminates the risk of uncollectible invoices, non-payment, and telecommunications fraud.
* **Frictionless Customer Cash Inflows:** Instant card charging via preset buttons ($25, $50, $100, $250) encourages frequent, friction-free wallet top-ups.
* **Continuous Service Continuity:** Auto-refill rules and low-balance warning alerts protect clients against dropped calls and unexpected outbound service interruptions.
* **Immutable Accounting Transparency:** Comprehensive transaction ledger details every top-up, monthly recurring plan deduction, and per-minute call charge.

---

## 3. 🎯 User Roles & Key Capabilities

| User Role | Primary Objectives | Key Capabilities in Add Funds & Wallet |
| :--- | :--- | :--- |
| **Enterprise Account Owner** | Maintains active communications funding for company operations. | Adds funds via card, reviews current balance, verifies credit limits, and checks account status. |
| **Accounts Payable & Finance** | Reconciles credit card statements with telecom expenses. | Audits transaction histories, cross-references Stripe receipt identifiers, and reviews deduction amounts. |
| **Call Center Supervisor** | Monitors trunk availability for high-volume outbound campaigns. | Ensures prepaid balances stay above minimum operating thresholds to prevent agent call disconnections. |
| **Billing & Risk Administrator** | Protects telephony platform from abusive traffic and fraud. | Configures customer billing types (`prepaid` vs `postpaid`), adjusts emergency credit limits, and audits ledger events. |

---

## 4. Prepaid Digital Wallet & Credit Limits

The Wallet overview screen presents an immediate executive summary of the customer's financial standing and operational status.

![Prepaid Wallet Overview](/screenshots/billing/client/wallet/wallet-overview.png)

### Core Wallet KPI Cards

* **Current Balance Card:**
  * Displays live usable funding available for telephony usage, plan renewals, and DID rentals (e.g., `$145.50 USD`).
  * Shows account operational status badge: `Active` (green) or `Suspended` (red).
* **Credit Limit Card:**
  * Indicates authorized overdraft or emergency cushion allowed before calls are barred (e.g., `$50.00 USD`).
  * Displays auto-refill configuration status (`Disabled` or `Enabled at $10.00`).
* **Account Type Card:**
  * Identifies the billing archetype (`prepaid` or `postpaid`).
  * Displays the permanent, immutable account number (`#ACC-10005`).

---

## 5. Instant Stripe Top-Up Modal, Presets & Payment Processing

Clicking the **+ Add Funds** button in the header or top action bar opens the **Add Funds to Wallet** modal.

![Add Funds to Wallet Modal](/screenshots/billing/client/wallet/add-funds-modal.png)

### Recharge Controls & Fields

| Field / Control | Type | Description |
| :--- | :--- | :--- |
| **Recharge Presets** | Button Grid | Quick-select buttons for standard denominations: **$25**, **$50**, **$100**, and **$250**. |
| **Custom Amount** | Numeric Input | Allows entering any custom dollar amount meeting the platform minimum (e.g., `$50`). |
| **Billing Method** | Selection | Displays the default saved payment method (e.g., `Default Saved Card / Vault`). |
| **Charge Button** | Action Button | Submits the payment intent to Stripe; displays animated progress spinner during authorization. |
| **Success Banner** | Confirmation | Displays a green checkmark and confirmation message upon successful wallet credit before auto-closing. |

---

## 6. Financial Ledger & Transaction Audit Trail

All balance modifications are permanently recorded in the immutable `transactions` table and displayed in the **Transaction History** table on the Wallet view.

### Ledger Entry Breakdown

| Transaction Type | Description | Impact on Balance | Example Ledger Description |
| :--- | :--- | :--- | :--- |
| **`topup`** | Customer payment via credit card, wire transfer, or PayPal. | **Positive (+)** | `Stripe Credit Card Auto-Refill (pi_3N9x...)` |
| **`charge`** | Monthly recurring plan fee or hardware rental deduction. | **Negative (-)** | `Monthly Recurring Subscription: Cloud Mini-PBX Business Pro` |
| **`usage`** | Aggregated call traffic or out-of-bundle minute debits. | **Negative (-)** | `PSTN Outbound Minutes Settlement (Cycle #104)` |
| **`refund`** | Administrative credit adjustment or disputed fee reversal. | **Positive (+)** | `Service Level Credit - Maintenance Window Overrun` |

---

## 7. Troubleshooting & Verification

### Auditing Customer Balance & Wallet in Database
```sql
SELECT 
    w.id AS wallet_id,
    c.id AS customer_id,
    c.name AS customer_name,
    c.account_number,
    w.balance,
    w.credit_limit,
    w.currency,
    w.auto_refill_enabled,
    w.auto_refill_threshold,
    w.auto_refill_amount
FROM wallets w
JOIN customers c ON c.id = w.customer_id
WHERE c.id = 5;
```

### Inspecting Recent Ledger Transactions
```sql
SELECT 
    id,
    type,
    amount,
    balance_after,
    description,
    reference_id,
    created_at
FROM transactions
WHERE customer_id = 5
ORDER BY created_at DESC
LIMIT 10;
```

---

## 8. Glossary

* **Digital Wallet:** An in-app electronic ledger storing client monetary credit used to settle recurring and pay-as-you-go telephony services.
* **Prepaid Billing:** A billing paradigm where services are consumed exclusively against pre-deposited funds, preventing debt accumulation.
* **Credit Limit:** An emergency financial threshold below $0.00 allowing critical voice calls to proceed even if the prepaid balance reaches zero.
* **PaymentIntent:** A Stripe API object representing a customer payment lifecycle from creation to authorization and settlement.
* **Double-Entry Ledger:** An accounting method where financial transactions require balanced debits and credits, ensuring financial auditability.