Diameter Ro API Reference¶

This document describes the REST API endpoints for managing Diameter Ro interface interactions for online charging in the TelcoAPI platform.

Endpoints¶

Initialize Credit Control Session¶

POST /v1/diameter/ro/ccr

Request Body:

{
  "session_id": "telco.api.com;1234567890;1",
  "destination_realm": "ocs.operator.com",
  "destination_host": "ocs1.operator.com",
  "cc_request_type": "INITIAL",
  "cc_request_number": 0,
  "service_context_id": "[email protected]",
  "subscription": {
    "imsi": "234150123456789",
    "msisdn": "447123456789",
    "service_identifier": 1,
    "rating_group": 100
  },
  "requested_service_unit": {
    "cc_time": 3600,
    "cc_total_octets": 1000000,
    "cc_input_octets": 500000,
    "cc_output_octets": 500000
  },
  "multiple_services_indicator": 1,
  "multiple_services_credit_control": [
    {
      "rating_group": 100,
      "service_identifier": 1,
      "requested_service_unit": {
        "cc_total_octets": 1000000
      }
    }
  ]
}

Response:

{
  "session_id": "telco.api.com;1234567890;1",
  "result_code": 2001,
  "auth_application_id": 4,
  "cc_request_type": "INITIAL",
  "cc_request_number": 0,
  "multiple_services_credit_control": [
    {
      "rating_group": 100,
      "service_identifier": 1,
      "granted_service_unit": {
        "cc_total_octets": 1000000,
        "cc_time": 3600,
        "validity_time": 7200
      },
      "result_code": 2001,
      "final_unit_indication": {
        "final_unit_action": "TERMINATE",
        "filter_id": ["block_all"]
      }
    }
  ],
  "credit_control_failure_handling": "TERMINATE"
}

Update Credit Control Session¶

PUT /v1/diameter/ro/ccr/{session_id}

Request Body:

{
  "cc_request_type": "UPDATE",
  "cc_request_number": 1,
  "multiple_services_credit_control": [
    {
      "rating_group": 100,
      "service_identifier": 1,
      "used_service_unit": {
        "cc_total_octets": 500000,
        "cc_input_octets": 200000,
        "cc_output_octets": 300000,
        "cc_time": 1800
      },
      "requested_service_unit": {
        "cc_total_octets": 1000000
      }
    }
  ]
}

Response:

{
  "result_code": 2001,
  "session_id": "telco.api.com;1234567890;1",
  "cc_request_type": "UPDATE",
  "cc_request_number": 1,
  "multiple_services_credit_control": [
    {
      "rating_group": 100,
      "service_identifier": 1,
      "granted_service_unit": {
        "cc_total_octets": 1000000,
        "cc_time": 3600
      }
    }
  ]
}

Terminate Credit Control Session¶

DELETE /v1/diameter/ro/ccr/{session_id}

Request Body:

{
  "cc_request_type": "TERMINATION",
  "cc_request_number": 2,
  "termination_cause": "DIAMETER_LOGOUT",
  "multiple_services_credit_control": [
    {
      "rating_group": 100,
      "service_identifier": 1,
      "used_service_unit": {
        "cc_total_octets": 800000,
        "cc_input_octets": 350000,
        "cc_output_octets": 450000,
        "cc_time": 2700
      }
    }
  ]
}

Response:

{
  "result_code": 2001,
  "session_id": "telco.api.com;1234567890;1",
  "cc_request_type": "TERMINATION",
  "cc_request_number": 2
}

Re-Authorization Request (RAR) Webhook¶

The platform will send RAR notifications to your configured webhook endpoint when the OCS initiates a re-authorization request.

Example webhook payload:

{
  "event": "diameter.ro.rar",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "session_id": "telco.api.com;1234567890;1",
    "re_auth_request_type": "AUTHORIZE_ONLY",
    "rating_group": 100,
    "service_identifier": 1
  }
}

Error Responses¶

Invalid AVP Format¶

{
  "type": "https://api.telcoapi.com/errors/validation-error",
  "title": "Invalid AVP Format",
  "status": 400,
  "detail": "Invalid rating group value. Must be a positive integer",
  "instance": "/diameter/ro/ccr"
}

Session Not Found¶

{
  "type": "https://api.telcoapi.com/errors/not-found",
  "title": "Session Not Found",
  "status": 404,
  "detail": "No active session found with ID telco.api.com;1234567890;1",
  "instance": "/diameter/ro/ccr/telco.api.com;1234567890;1"
}

OCS Connection Error¶

{
  "type": "https://api.telcoapi.com/errors/connection-error",
  "title": "OCS Connection Error",
  "status": 503,
  "detail": "Unable to establish connection with OCS ocs1.operator.com",
  "instance": "/diameter/ro/ccr"
}

AVP Definitions¶

Common AVPs¶

AVP Name	Code	Type	Description
Session-Id	263	UTF8String	Unique session identifier
Origin-Host	264	DiameterIdentity	Origin host identity
Origin-Realm	296	DiameterIdentity	Origin realm identity
Destination-Realm	283	DiameterIdentity	Destination realm identity
CC-Request-Type	416	Enumerated	Type of credit control request
CC-Request-Number	415	Unsigned32	Credit control request sequence number

Ro Specific AVPs¶

AVP Name	Code	Type	Description
Service-Context-Id	461	UTF8String	Service context identifier
Multiple-Services-Credit-Control	456	Grouped	Granted/requested units per service
Requested-Service-Unit	437	Grouped	Service units requested
Used-Service-Unit	446	Grouped	Service units used
Granted-Service-Unit	431	Grouped	Service units granted

Rate Limits¶

Plan	Requests per Second	Burst
Basic	10	20
Premium	50	100
Enterprise	200	400