Billing & OCS Settings

Table of Contents

1. Overview & Integration Architecture
2. Business & Operational Significance
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Form Layout
5. Configuration Parameters Reference
6. Real-Time OCS Call Flow & Signaling Mechanics
7. Fallback Policies & Fraud Governance
8. Troubleshooting & Verification
9. Model Context Protocol (MCP) AI Integration
10. Glossary

---

1. Overview & Integration Architecture

In Ring2All SBC, the Billing & OCS module orchestrates real-time interconnectivity between the Kamailio perimeter signaling core and the Ring2All BSS Online Charging System (OCS) (or any 3GPP/RFC-compliant telecom rating engine). Through non-blocking asynchronous HTTP/REST queries, the SBC verifies account balances, checks prepaid credit limits, and enforces maximum call duration allowances before routing calls to downstream carrier gateways.

Caller (SIP Endpoint)            Ring2All SBC (Kamailio Core)               Ring2All BSS OCS Engine
          │                                  │                                       │
          │─────── SIP INVITE ──────────────>│                                       │
          │<────── 100 Trying ───────────────│                                       │
          │                                  │─── POST /api/v1/ocs/authorize ───────>│
          │                                  │    {caller, callee, domain, rate}     │
          │                                  │                                       │
          │                                  │<── HTTP 200 OK (Authorized) ──────────│
          │                                  │    {allowed: true, max_seconds: 300}  │
          │                                  │                                       │
          │                                  │─── Set Dialog Timeout (300s) ─────────┐
          │                                  │                                       │
          │─────── 180 Ringing / 200 OK ─────│<──────────────────────────────────────┘
          │═══════ Active Call ══════════════│

By decoupling billing logic from the core SIP state machine via asynchronous workers (http_async_client), the SBC guarantees that charging queries do not block UDP worker processes or increase call setup latency.

---

2. Business & Operational Significance

• Zero-Balance Fraud Elimination: Prevents wholesale and retail subscribers from placing high-cost international or premium-rate calls without verified prepaid funds or approved credit lines.
• Granular Session Duration Clamping: Dynamically sets dialog timers (dialog.timeout) based on the caller’s available balance and target destination rate, automatically terminating the call before debt occurs.
• Carrier Interconnect Revenue Assurance: Guarantees that wholesale accounts cannot exceed strictly defined daily or hourly credit thresholds.
• Fault-Tolerant Fallback Handling: Provides deterministic policies (Reject, Allow, or Divert) when the OCS engine is unreachable, safeguarding platform availability during network outages.

---

3. 🎯 User Roles & Key Capabilities

Role	Primary Use Case	Key Capabilities
Telecom Billing Administrator	Real-Time Charging Configuration	Configure OCS API endpoints, tune request timeouts, and align session safety caps with billing rate cards.
Carrier Interconnect Manager	Credit Risk & Quota Oversight	Audit credit check behaviors, inspect real-time authorization latencies, and monitor balance rejections.
SBC Operations Engineer	Engine Interconnect Tuning	Optimize asynchronous HTTP worker threads and verify network socket health between the SBC and the OCS cluster.
Fraud & Risk Analyst	Abuse & Overrun Prevention	Define strict fallback policies to automatically reject unverified outbound calls during billing server degradation.
AI Billing Auditor / NOC Copilot	Autonomous Health Auditing	Execute real-time OCS endpoint probes, verify authorization latencies, and adjust fallback risk profiles under incident response via MCP.

---

4. Visual Interface & Form Layout

The Billing & OCS configuration interface provides intuitive controls for enabling charging integrations, setting API connection details, configuring timeouts, and selecting fallback policies.

---

5. Configuration Parameters Reference

Parameter Name	Data Type	Default Value	Description
Enable Real-Time OCS	Switch	Enabled	Master toggle to enforce real-time credit checks on all outbound or rated ingress SIP transactions.
OCS Engine Endpoint URL	Text / URL	http://127.0.0.1:8080/api/v1/ocs/authorize	Fully qualified HTTP/HTTPS endpoint where the SBC transmits session authorization JSON payloads.
API Authentication Token	Password / Text	Bearer eyJ...	Secure API key or JWT Bearer token passed in the Authorization header for OCS access control.
Request Timeout (ms)	Integer	1500	Maximum time in milliseconds the SBC will wait for an OCS response before triggering the fallback policy.
Fallback Policy	Select	Reject Call (503)	Action taken when OCS returns an HTTP 5xx error or times out: Reject Call (503), Allow Call (Free), or Route to IVR.
Safety Cap Duration (sec)	Integer	7200	Absolute upper limit in seconds (default 2 hours) for any single session, regardless of balance.
Cache Authorization TTL	Integer	0	Time-to-live in seconds for caching balance authorizations (0 disables caching, forcing fresh lookups).
Async HTTP Concurrency	Integer	16	Number of non-blocking worker threads dedicated to handling outbound OCS HTTP requests.

---

6. Real-Time OCS Call Flow & Signaling Mechanics

The authorization workflow is embedded directly within the Kamailio routing script using the http_async_client and dialog modules:

1. Transaction Interception: Upon receiving an initial INVITE, the SBC evaluates whether the source domain or account requires real-time rating.
2. Asynchronous Dispatch: The SBC suspends the transaction and dispatches a JSON payload containing caller ID, destination number, and tenant UUID:

   {
     "event": "session_authorize",
     "call_id": "98a7bc-12df-48aa-b97c-91823ab0281@sbc",
     "caller": "2000",
     "callee": "+14155552671",
     "domain": "customer-pbx.ring2all.com",
     "timestamp": 1757268000
   }

3. Response Processing:
   • Approved (HTTP 200): If the response contains "authorized": true and "max_duration": 480, Kamailio resumes the transaction, routes the call to the carrier gateway, and sets dlg_set_timeout(480).
   • Insufficient Funds (HTTP 402): If the balance is zero, Kamailio immediately replies to the caller with SIP/2.0 402 Payment Required and generates an audit log entry.
   • Timeout / Error: If no response arrives within the configured Request Timeout, the engine activates the configured Fallback Policy.

---

7. Fallback Policies & Fraud Governance

Choosing the correct fallback policy is critical for balancing business continuity against financial risk:

• Reject Call (SIP 503 Service Unavailable) [Recommended for Wholesale]: Guarantees zero revenue leakage. If the billing engine is unreachable, no unauthorized calls are permitted to exit the network.
• Allow Call (Free) [Recommended for Critical Enterprise]: Prioritizes high-priority enterprise communication continuity. Calls are allowed to proceed, and billing records are queued locally for retrospective settlement once OCS recovers.
• Route to Emergency / Notification IVR: Diverts the call to an internal media server announcement explaining that billing services are temporarily undergoing maintenance.

---

8. Troubleshooting & Verification

Manual OCS Endpoint Health Probe

Validate that the OCS API responds within the SLA window directly from the SBC host:

curl -s -w "\nHTTP: %{http_code} | Total Time: %{time_total}s\n" \
  -H "Authorization: Bearer YOUR_OCS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"caller":"2000","callee":"+14155552671","domain":"test.ring2all.com"}' \
  http://127.0.0.1:8080/api/v1/ocs/authorize

Inspecting Asynchronous HTTP Metrics

In the RPC Console, check the health of the asynchronous HTTP worker queues:

http_async_client.status

---

9. Model Context Protocol (MCP) AI Integration

The Billing & OCS subsystem exposes dedicated Model Context Protocol (MCP) tools for real-time rating auditability, dynamic parameter tuning, and synthetic connectivity diagnostics by LLM agents.

Available MCP Tools

Tool Name	Operation Type	Risk Level	Description
get_billing_settings	Status Query	read	Retrieve active OCS connection parameters, API endpoint URL, timeout thresholds, fallback policy, and safety caps.
update_billing_settings	Configuration Mutation	operational	Update real-time OCS configuration including endpoint URL, fallback action, request timeouts, and safety caps.
test_billing_connection	Diagnostic Verification	read	Transmit a synthetic test authorization request to the configured OCS endpoint and measure round-trip HTTP latency.

Tool Schemas & Payloads

1. get_billing_settings

Input Schema

{
  "type": "object",
  "properties": {}
}

Output Payload Example

{
  "success": true,
  "data": {
    "enabled": true,
    "endpoint_url": "http://127.0.0.1:8080/api/v1/ocs/authorize",
    "request_timeout_ms": 1500,
    "fallback_policy": "reject",
    "safety_cap_seconds": 7200,
    "cache_ttl": 0,
    "async_workers": 16,
    "updated_at": "2026-09-08T14:40:00.000Z"
  }
}

2. update_billing_settings

Input Schema

{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Master switch to enable or disable real-time OCS authorization checks."
    },
    "endpoint_url": {
      "type": "string",
      "description": "Fully qualified HTTP/HTTPS URL of the Ring2All BSS or external OCS rating engine."
    },
    "request_timeout_ms": {
      "type": "number",
      "description": "HTTP request timeout in milliseconds before triggering fallback policy (e.g. 1500)."
    },
    "fallback_policy": {
      "type": "string",
      "enum": ["reject", "allow", "route_ivr"],
      "description": "Policy to adopt when OCS is unreachable or times out."
    },
    "safety_cap_seconds": {
      "type": "number",
      "description": "Maximum allowable call duration in seconds regardless of authorized balance."
    }
  }
}

Output Payload Example

{
  "success": true,
  "data": {
    "message": "Billing settings updated successfully."
  }
}

3. test_billing_connection

Input Schema

{
  "type": "object",
  "properties": {
    "endpoint_url": {
      "type": "string",
      "description": "Optional override URL to test prior to applying permanent configuration changes."
    },
    "api_token": {
      "type": "string",
      "description": "Optional override bearer token to validate authentication headers."
    }
  }
}

Output Payload Example

{
  "success": true,
  "data": {
    "reachable": true,
    "status_code": 200,
    "response_time_ms": 38,
    "details": "OCS endpoint responded with HTTP 200 OK."
  }
}

Natural Language AI Prompts

English Examples

• “Check the active OCS billing settings and verify if real-time rating is currently enabled.”
• “Test the connection to the billing authorization endpoint and report the response latency.”
• “Set the OCS request timeout to 1200ms and switch the fallback policy to reject calls on failure.”

Spanish Examples (Español)

• “Verifica los ajustes de facturación OCS activos y comprueba si la tarificación en tiempo real está habilitada.”
• “Prueba la conexión hacia el endpoint de autorización de facturación y reporta la latencia de respuesta.”
• “Configura el timeout de petición OCS a 1200ms y cambia la política de contingencia a rechazar llamadas.”

Enterprise Safeguards & Access Governance

1. Token Masking: Secret API tokens and bearer authentication keys are never returned in plain text via get_billing_settings payloads.
2. Fail-Closed Protection: Wholesale interconnect configurations mandate reject fallback to prevent unbilled call termination during billing outages.
3. Non-Blocking Execution: Synthetic connectivity probes execute via isolated asynchronous HTTP workers without delaying active call processing pipelines.

---

10. Glossary

• OCS (Online Charging System): A core telecom element that performs real-time credit checks, rating, and balance reservation during active voice calls.
• Asynchronous Suspension: Temporarily parking a SIP transaction without consuming POSIX worker threads while waiting for external HTTP API responses.
• Safety Cap: A hard stop parameter that forcefully disconnects a call once it reaches a maximum allowable duration.
• Dialog Timeout (dlg_timeout): A timer maintained in Kamailio shared memory that automatically sends BYE teardown packets to both legs if the session exceeds authorized seconds.