Customers & Accounts Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial & Business Value)
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Form Structure
5. Architectural Flow & Multi-Tenant Convergence
6. Common Scenarios & Operational Playbooks
7. Troubleshooting & Diagnostic Commands
8. Model Context Protocol (MCP) AI Integration
9. Glossary

---

1. Module Overview (Technical)

The Customers & Accounts module (public.customers) constitutes the foundational multi-tenant identity and ledger registry within Ring2All Billing. It unifies commercial contract profiles, prepaid credit wallets (public.wallets), postpaid credit terms, automated tax jurisdictions, and bidirectional synchronization across voice core infrastructure—specifically Ring2All PBX (ring2all_tenant_id) and Ring2All SBC (sbc_customer_id).

Data Model & System Linkage

 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Customer Entity (public.customers)                │
 │  • id: bigint (Canonical Invariant Numeric ID)                         │
 │  • uuid: uuid (Public API Identifier)                                  │
 │  • account_number: VARCHAR(50) (e.g. "ACC-10005")                      │
 │  • company_name: VARCHAR(100) (e.g. "Acme Telecom Corp")               │
 │  • billing_type: 'prepaid' | 'postpaid'                                │
 │  • balance: NUMERIC(14,4) | credit_limit: NUMERIC(14,4)                │
 │  • ring2all_tenant_id: bigint (Linkage to Ring2All Class 5 Tenant)     │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┴─────────────────────────┐
           │                                                   │
           ▼ (1 Customer = 1 PBX Tenant)                       ▼ (1 Customer = N SIP Trunks)
 ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
 │     Ring2All PBX (Class 5 Core)   │               │     Ring2All SBC (Class 4 Core)   │
 │  • Tenant ID: 12                  │               │  • SIP Trunk: "Acme-HQ-GW"        │
 │  • Domains: voice.acme.com        │               │  • Dispatcher Set: ID 102         │
 │  • Extension Quota Enforcement    │               │  • Anti-Fraud Balance Cutoff      │
 └───────────────────────────────────┘               └───────────────────────────────────┘

PostgreSQL Schema Architecture (public.customers)

• Primary Key: id (bigserial) ensures strict immutability. Slugs, corporate names, and alphanumeric codes are strictly prohibited as primary relational foreign keys.
• Wallet Linkage: Every customer is atomically assigned an encrypted monetary ledger (public.wallets) supporting sub-cent precision (NUMERIC(14,4)) for real-time rating and balance sweeps.
• Auto-Provisioning Flags: Configurable flags allow automated instant provisioning of Ring2All PBX domains and Ring2All SBC SIP accounts upon account creation.

---

2. Module Overview (Commercial & Business Value)

• Converged Financial Control: Eliminates silos between Class 4 wholesale VoIP transit billing and Class 5 hosted cloud PBX subscription billing by centralizing all recurring and metered receivables into a single customer ledger.
• Credit Exposure & Default Risk Elimination: Real-time OCS (Online Charging System) balance monitoring prevents carrier debt by instantly intercepting live calls and dropping dialogs when prepaid balances reach zero or postpaid credit limits are breached.
• Automated Dunning & Lifecycle Transitions: Automated state machine sweeps manage transitions from active → past_due → suspended → closed, triggering automated webhook and email notifications.

---

3. 🎯 User Roles & Key Capabilities

User Role	Key Permissions	Core Responsibilities & Workflows
Super Administrator	Full Control (CRUD, Billing Overrides)	Defines global billing parameters, approves multi-thousand dollar credit limits, manually overrides customer wallet balances, and executes debt write-offs.
Billing Analyst / NOC	Read, Edit, Payment Management	Enrolls new corporate accounts, reviews billing ledger statements, verifies automated credit card transactions, and handles dunning investigations.
Telecom Engineer	Read & Provisioning Mapping	Verifies that customer accounts are correctly synced with Ring2All PBX tenants and Ring2All SBC dispatchers and IP authorization endpoints.
Client Portal Customer	Self-Service Read & Payments	Views real-time wallet balance, downloads PDF invoices, pays bills via Stripe, and inspects rated CDR summaries.

---

4. Visual Interface & Form Structure

4.1 Customers Management (List View)

The Customers Management view provides a high-density, real-time DataGrid displaying all corporate accounts with instant search, status filtering, and action menus.

4.2 Customer Configuration Form (Form View)

The Customer Configuration form manages granular account properties across multi-tabbed sections: General Details, Billing & Invoicing, IP Authentication Endpoints, and Assigned Rate Cards.

4.3 Form Parameter Reference

Parameter Name	Data Type	Required	Default Value	Description & Business Rules
Company / Account Name	String	Yes	—	Official legal corporate entity name used on all tax invoices and contractual billing summaries.
Account Number	String	Yes	Auto-generated	Canonical account code (e.g. ACC-10005). Used for bank transfers, invoice referencing, and ERP reconciliation.
Billing Mode	Enum	Yes	prepaid	prepaid (requires positive wallet balance prior to call completion) or postpaid (invoiced periodically on net-terms).
Credit Limit	Numeric	No	0.00	Maximum allowable negative balance for postpaid customers before outbound traffic is automatically halted.
Billing Currency	String	Yes	USD	ISO-4217 3-letter currency code (USD, EUR, CAD, GBP) governing all ledger debits and rate card matching.
Payment Terms	Enum	Yes	due_on_receipt	Invoicing schedule: due_on_receipt, net_15, net_30, net_60. Dictates overdue interest and suspension triggers.
Primary Contact Email	Email	Yes	—	Destination for automated PDF invoice dispatches, payment failure receipts, and balance threshold warnings.
Tax ID / VAT Number	String	No	—	Corporate tax identifier for fiscal compliance and automated tax exemption checks.
Ring2All PBX Tenant ID	Integer	No	—	Invariant numeric ID of the corresponding Class 5 tenant in Ring2All PBX for unified billing sync.
Account Status	Enum	Yes	active	Account lifecycle state: active (normal service), suspended (calls blocked), fraud_hold (security lockout), closed.

---

5. Architectural Flow & Multi-Tenant Convergence

   Incoming Call / Rating Event
                 │
                 ▼
 ┌─────────────────────────────────┐
 │   Ring2All SBC / PBX OCS Check  │
 └───────────────┬─────────────────┘
                 │ Queries Customer Balance
                 ▼
 ┌─────────────────────────────────┐
 │     public.customers Entity     │
 ├─────────────────────────────────┤
 │ Mode: prepaid                   │
 │ Wallet Balance: $49.95          │
 │ Status: active                  │
 └───────────────┬─────────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
 Balance > $0.00    Balance <= $0.00
        │                 │
        ▼                 ▼
 Call Authorized    Call Dropped with SIP 402
 (Real-time debit)  "Payment Required"

---

6. Common Scenarios & Operational Playbooks

Scenario A: Enrolling an Enterprise Postpaid Account

1. Navigate to Customer Accounts → Customers and click + Add.
2. Enter the legal company name and primary billing email.
3. Set Billing Mode to Postpaid, configure Credit Limit to $500.00, and select Payment Terms as net_30.
4. In the Associated Rate Card dropdown, select the enterprise retail rate card (e.g. Standard Retail Rate Card).
5. Click Save Customer. The platform automatically generates the invariant numeric ID and dispatches welcome instructions.

Scenario B: Emergency Account Suspension (Fraud or Non-Payment)

1. In the customer list, locate the offending account and open the editor.
2. In Account Status, toggle from Active to Suspended or Fraud Hold.
3. Save changes. The backend immediately dispatches an RPC signal to Ring2All SBC and Ring2All PBX to drop all active calls and reject subsequent SIP INVITE attempts.

---

7. Troubleshooting & Diagnostic Commands

Verifying Customer Balance & Invariant Linkage (PostgreSQL)

su - postgres -c "psql -d ss_billing -c \"
SELECT c.id, c.account_number, c.company_name, c.billing_type, c.status,
       w.balance, c.credit_limit, c.ring2all_tenant_id
FROM customers c
LEFT JOIN wallets w ON w.customer_id = c.id
WHERE c.id = 1;\""

Checking Active Customer State via REST API

curl -s -k -X GET "https://192.168.10.29/api/v1/customers/1" \
  -H "Authorization: Bearer <TOKEN>" | jq .

---

8. Model Context Protocol (MCP) AI Integration

The Customers & Accounts module natively connects to the Ring2All BSS MCP Server. Autonomous agents, billing operations copilots, and credit analysts interact with customer ledgers, inspect balances, and execute policy adjustments through structured conversational tools.

Available MCP Tools

Tool Name	Access Role	Description & Primary Function	Example Arguments
list_billing_customers	Billing Operations / Admin	Lists carrier customers, balances, credit limits, and account statuses.	{"limit": 10, "status": "active"}
get_billing_customer	Billing Operations / Admin	Retrieves full financial profile including wallet balance, DIDs, and subscriptions.	{"customerId": "1"}
adjust_customer_balance	Super Administrator	Credits or debits customer wallet with immutable audit ledger recording.	{"customerId": "1", "amount": 50.00, "description": "Manual top-up"}
update_customer_status	Super Administrator	Modifies operational status (active, suspended, fraud_hold).	{"customerId": "1", "status": "suspended", "reason": "Non-payment"}
get_customer_wallet_ledger	Billing Operations / Admin	Queries recent ledger entries (top-ups, call debits, recurring charges).	{"customerId": "1", "limit": 10}

Sample MCP Tool Execution: get_billing_customer

Request Payload

{
  "name": "get_billing_customer",
  "arguments": {
    "customerId": "1"
  }
}

Response Payload

{
  "id": "1",
  "name": "Rodrigo Cuadra",
  "company": "Cuadra Telecom Corp",
  "accountNumber": "ACC-10042",
  "billingType": "prepaid",
  "status": "active",
  "balance": "$248.50",
  "creditLimit": "$0.00",
  "currency": "USD",
  "assignedDidsCount": 4,
  "activeSubscriptionsCount": 2
}

Conversational AI Prompts for Copilot

• “List all customers with negative balances or suspended accounts.”
• “What is the current wallet balance and assigned DIDs count for customer ACC-10042?”
• “Suspend customer 1 due to suspected IRSF fraud velocity alert.”
• “Show the last 5 ledger transactions recorded for customer 1.”

---

9. Glossary

• BSS (Business Support System): Software handling customer accounts, invoicing, payments, subscriptions, and financial ledgers.
• OCS (Online Charging System): Real-time rating engine capable of interrogating wallet balances before and during telephone calls.
• Canonical Numeric ID: Immutable database integer key (id) used for all relational constraints and inter-service communications.
• Dunning: Automated process of tracking delinquent accounts, issuing payment reminders, and triggering service suspensions.
• Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.