---
title: "Billing & OCS Settings"
description: "Documentation for Billing & OCS"
---

## Table of Contents
1. [Overview & Integration Architecture](#1-overview--integration-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Layout](#4-visual-interface--form-layout)
5. [Configuration Parameters Reference](#5-configuration-parameters-reference)
6. [Real-Time OCS Call Flow & Signaling Mechanics](#6-real-time-ocs-call-flow--signaling-mechanics)
7. [Fallback Policies & Fraud Governance](#7-fallback-policies--fraud-governance)
8. [Troubleshooting & Verification](#8-troubleshooting--verification)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#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.

![Billing and OCS Settings View](/screenshots/sbc/settings/technology/billing/billing-settings.png)

---

## 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:
   ```json
   {
     "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:
```bash
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:
```bash
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
```json
{
  "type": "object",
  "properties": {}
}
```

##### Output Payload Example
```json
{
  "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
```json
{
  "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
```json
{
  "success": true,
  "data": {
    "message": "Billing settings updated successfully."
  }
}
```

#### 3. `test_billing_connection`

##### Input Schema
```json
{
  "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
```json
{
  "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.