Insurance & Coverage Service

Pipeline-Managed Service

This service is deployed and managed by its CI/CD pipeline.

For current deployment status, configurations, and code:

Repository: https://repo.local/healthflow/ndp-insurance-service
Technology: Go/Gin Framework
Version: v1.5.0

Overview

The Insurance & Coverage Service handles all interactions with Egypt's Universal Health Insurance System (UHIS) and private insurance providers. It provides real-time eligibility verification, coverage determination, prior authorization, copayment calculation, and claims processing.

REQUIRED FOR DISPENSING

Prescriptions cannot be dispensed without verified insurance coverage (unless patient pays cash).

Real-time eligibility required
Copayment must be calculated
Prior authorization for restricted drugs

Purpose

Primary Functions

Real-time Eligibility Verification with UHIS
Coverage Determination for medications
Prior Authorization management
Copayment Calculation
Claims Submission and tracking
Formulary Compliance checking
Step Therapy enforcement
Coordination of Benefits (multiple insurances)

Egypt Healthcare Context

UHIS Structure:

Universal coverage for all Egyptian citizens
Phased rollout by governorate (2018-2032)
Comprehensive benefit package
Copayments for services/medications
Private insurance as supplementary

Architecture

Key Features

1. Real-Time Eligibility Verification

Eligibility Check:

typescript

interface EligibilityRequest {
  patientId: string; // National ID
  providerId: string; // HPR ID
  facilityId: string; // Facility ID
  serviceDate: Date; // Date of service
  serviceType: "PRESCRIPTION" | "PHARMACY" | "MEDICAL";
}

interface EligibilityResponse {
  eligible: boolean;
  insuranceInfo: {
    providerId: string; // UHIS or private
    providerName: string; // "UHIS" or "MetLife Egypt"
    memberNumber: string; // Insurance member ID
    planType: string; // "STANDARD" | "ENHANCED" | "VIP"
    effectiveDate: Date;
    terminationDate: Date;
    status: "ACTIVE" | "INACTIVE" | "SUSPENDED";
  };
  coverage: {
    prescriptionBenefit: boolean;
    pharmacyBenefit: boolean;
    copayRequired: boolean;
    annualLimit: number; // EGP
    remainingLimit: number; // EGP
    deductible: number;
    deductibleMet: number;
  };
  restrictions: string[]; // ["Requires Prior Authorization for high-cost drugs"]
  message: string;
}

Caching Strategy:

Eligibility cached for 24 hours
Real-time check for high-value claims
Automatic cache invalidation on plan changes

2. Coverage Determination

Formulary Tiers:

Tier	Description	Coverage	Copayment
Tier 1	Preferred Generic	100%	5 EGP
Tier 2	Generic	90%	10 EGP
Tier 3	Preferred Brand	75%	25 EGP
Tier 4	Non-Preferred Brand	50%	50 EGP
Tier 5	Specialty/Biologics	Varies	100-500 EGP
Non-Formulary	Not covered	0%	Full cost

Step Therapy:

yaml

Example: Diabetes Medications
  Step 1 (Required First):
    - Metformin (generic)
    Coverage: Tier 1, 100%

  Step 2 (If Step 1 fails):
    - Sulfonylureas (Glimepiride)
    - DPP-4 inhibitors
    Coverage: Tier 2, 90%
    Requires: Documentation of Step 1 trial

  Step 3 (If Steps 1-2 fail):
    - GLP-1 agonists
    - SGLT2 inhibitors
    Coverage: Tier 3-4, 50-75%
    Requires: PA with documented failure of Steps 1-2

  Step 4 (Specialist Only):
    - Insulin analogs
    Coverage: Tier 3, 75%
    Requires: Endocrinologist prescription + PA

3. Prior Authorization (PA)

PA Required For:

High-cost medications (>1000 EGP/month)
Specialty medications (biologics, chemotherapy)
Non-formulary drugs
Quantities exceeding limits
Step therapy overrides

PA Workflow:

PA Request Data:

typescript

interface PriorAuthRequest {
  paNumber: string; // Auto-generated
  requestDate: Date;
  patientId: string;
  prescriberId: string;
  facilityId: string;

  medication: {
    code: string;
    name: string;
    quantity: number;
    daysSupply: number;
    estimatedCost: number; // EGP
  };

  clinicalJustification: {
    diagnosis: string; // ICD-10
    previousTreatments: string[]; // Failed therapies
    clinicalNotes: string;
    supportingDocuments: string[]; // Lab results, specialist notes
    urgency: "ROUTINE" | "URGENT" | "EMERGENCY";
  };

  status: PAStatus;
  reviewNotes: string;
  reviewedBy: string;
  reviewDate: Date;
  expirationDate: Date; // Typically 90 days
}

type PAStatus =
  | "PENDING"
  | "PENDING_ADDITIONAL_INFO"
  | "UNDER_REVIEW"
  | "APPROVED"
  | "DENIED"
  | "APPEALED"
  | "EXPIRED";

PA Processing Times:

Routine: 72 hours
Urgent: 24 hours
Emergency: 4 hours (verbal authorization, paperwork follows)

4. Copayment Calculation

typescript

interface CopaymentCalculation {
  prescriptionId: string;

  medication: {
    code: string;
    name: string;
    quantity: number;
    unitPrice: number;            // EGP per unit
    totalCost: number;            // quantity × unitPrice
  };

  coverage: {
    tier: number;                 // 1-5
    coveragePercent: number;      // 50-100%
    insurancePays: number;        // EGP
    baseCopayment: number;        // Tier-based copay
  };

  adjustments: {
    deductibleApplied: number;    // If deductible not met
    exceededLimit: number;        // If annual limit exceeded
    priorAuthSurcharge: number;   // If PA required but not obtained
  };

  finalAmounts: {
    patientPays: number;          // Total patient responsibility
    insurancePays: number;        // Total insurance pays
    breakdown: string;            // Explanation
  };
}

Example Calculation:
  Medication: Atorvastatin 40mg × 30 tablets
  Unit Price: 5 EGP
  Total Cost: 150 EGP

  Coverage:
    Tier: 2 (Generic)
    Coverage: 90%
    Tier Copay: 10 EGP

  Calculation:
    Insurance Pays: 150 × 90% = 135 EGP
    Patient Copay: 10 EGP (tier copay)
    Total Patient: 10 EGP + (150 - 135) = 25 EGP

    Note: Patient pays GREATER of:
      - Tier copay (10 EGP)
      - OR Coinsurance amount (15 EGP)
    Result: 15 EGP

5. Claims Processing

Claim Types:

Real-time (POS): Point-of-sale, immediate adjudication
Batch: Submit daily, response within 24-48 hours
Paper: Last resort, 7-14 day turnaround

Claim Lifecycle:

yaml

Claim Submission:
  1. Prescription dispensed at pharmacy
  2. Claim created with NDC, quantity, cost
  3. Submitted via EDI (NCPDP standard)
  4. Real-time adjudication (usually <3 seconds)
  5. Approval/Denial response
  6. If approved: Payment scheduled
  7. If denied: Denial reason provided

Claim Statuses:
  - DRAFT: Being prepared
  - SUBMITTED: Sent to insurance
  - PROCESSING: Under review
  - APPROVED: Payment authorized
  - PAID: Payment completed
  - DENIED: Claim rejected
  - APPEALED: Under appeal
  - VOIDED: Cancelled

NCPDP Claim Format (Simplified):

json

{
  "transactionCode": "B1", // Billing request
  "versionNumber": "D.0",
  "transactionCount": 1,

  "insuranceSegment": {
    "cardholderID": "UHIS-123456789",
    "groupID": "UHIS-STD",
    "personCode": "01", // Cardholder
    "relationshipCode": "1" // Self
  },

  "patientSegment": {
    "patientID": "29001010101010",
    "dateOfBirth": "1990-01-01",
    "gender": "M"
  },

  "claimSegment": {
    "prescriptionNumber": "RX-2026-000001",
    "productID": "12345678901", // NDC
    "quantityDispensed": 30,
    "daysSupply": 30,
    "ingredientCost": 120.0,
    "dispensingFee": 5.0,
    "totalCost": 125.0,
    "dateOfService": "2026-04-12"
  },

  "prescriberSegment": {
    "prescriberID": "HPR-12345",
    "prescriberNPI": "1234567890"
  }
}

6. Coordination of Benefits (COB)

For patients with multiple insurance:

yaml

COB Rules:
  Primary Insurance:
    - Pays first according to its rules
    - Calculates copayment

  Secondary Insurance:
    - Covers patient's remaining balance
    - Up to secondary plan limits

  Example:
    Total Cost: 200 EGP

    Primary (UHIS):
      Coverage: 75%
      Pays: 150 EGP
      Patient Balance: 50 EGP

    Secondary (Private):
      Covers: Remaining balance
      Pays: 50 EGP
      Final Patient Pays: 0 EGP

    Note: Secondary never pays more than patient's balance

API Endpoints

Eligibility

yaml

POST /api/v1/insurance/eligibility
{
  "patientId": "29001010101010",
  "serviceDate": "2026-04-12",
  "providerId": "HPR-12345"
}

Response:
{
  "eligible": true,
  "insuranceInfo": {...},
  "coverage": {...}
}

Coverage Check

yaml

POST /api/v1/insurance/coverage-check
{
  "patientId": "29001010101010",
  "medications": [
    {
      "code": "MED-001",
      "quantity": 30,
      "daysSupply": 30
    }
  ]
}

Response:
{
  "medications": [
    {
      "code": "MED-001",
      "covered": true,
      "tier": 2,
      "coveragePercent": 90,
      "estimatedCopayment": 15,
      "requiresPA": false,
      "stepTherapy": null
    }
  ]
}

Prior Authorization

yaml

# Submit PA
POST /api/v1/insurance/prior-authorization
{
  "patientId": "29001010101010",
  "medicationCode": "MED-EXPENSIVE",
  "clinicalJustification": {...}
}

# Check PA Status
GET /api/v1/insurance/prior-authorization/{paNumber}

# Appeal Denied PA
POST /api/v1/insurance/prior-authorization/{paNumber}/appeal
{
  "appealReason": "...",
  "additionalDocumentation": [...]
}

Claims

yaml

# Submit Claim (Real-time)
POST /api/v1/insurance/claims/submit
{
  "prescriptionId": "RX-2026-000001",
  "dispensingDetails": {...}
}

# Check Claim Status
GET /api/v1/insurance/claims/{claimNumber}

# Void/Reverse Claim
POST /api/v1/insurance/claims/{claimNumber}/void

Integration Points

UHIS Central System

Connection: Secure VPN tunnel
Protocol: SOAP/XML (legacy) + REST/JSON (new)
Authentication: Mutual TLS + API keys
Rate Limits: 1000 req/min per facility

Private Insurance APIs

MetLife Egypt: REST API
AXA Egypt: REST API
Allianz Egypt: EDI Gateway
Others: NCPDP standard EDI

Internal Services

Prescription Service: Coverage verification
Dispense Service: Real-time claim submission
Patient Registry: Insurance member info
Medicine Directory: NDC codes, pricing

Performance & Scalability

yaml

resources:
  limits:
    cpu: "2"
    memory: 4Gi
  requests:
    cpu: "1"
    memory: 2Gi

replicas: 5

autoscaling:
  minReplicas: 5
  maxReplicas: 20
  targetCPUUtilization: 70

Performance Targets

Operation	Target	P95
Eligibility Check	< 500ms	< 1s
Coverage Check	< 300ms	< 800ms
Real-time Claim	< 3s	< 5s
PA Submission	< 1s	< 2s

Configuration

yaml

# UHIS Configuration
uhis:
  api_url: https://insurance.gov.eg/api
  soap_endpoint: https://insurance.gov.eg/soap
  client_certificate: /certs/uhis-client.pem
  timeout: 30s
  retry_attempts: 3

# Private Insurers
private_insurers:
  metlife:
    enabled: true
    api_url: https://api.metlife.eg
    api_key: ${METLIFE_API_KEY}
  axa:
    enabled: true
    api_url: https://api.axa.eg
    api_key: ${AXA_API_KEY}

# EDI Configuration
edi:
  gateway_url: https://edi.ndp.eg
  ncpdp_version: "D.0"
  batch_schedule: "0 1 * * *" # 1 AM daily

# Caching
cache:
  eligibility_ttl: 86400 # 24 hours
  coverage_ttl: 3600 # 1 hour
  redis_url: redis://redis.data-stack:6379

# Business Rules
business_rules:
  pa_required_threshold: 1000 # EGP
  pa_expiration_days: 90
  claim_resubmission_days: 30
  appeal_window_days: 30

Business Rules

Prior Authorization Criteria

yaml

Auto-Approve PA:
  - Cost < 1000 EGP
  - Generic formulary drug
  - No step therapy requirement
  - Patient has not exceeded limits

Requires Manual Review:
  - Cost > 5000 EGP/month
  - Non-formulary drugs
  - Step therapy override
  - Experimental/investigational
  - Compound medications

Auto-Deny (can appeal):
  - Cosmetic use
  - Not medically necessary
  - Adequate alternatives available
  - Patient not eligible

Claim Denial Reasons

yaml

Common Denial Codes:
  70: Patient not eligible on service date
  75: Prior authorization required
  76: Duplicate claim
  88: Drug not covered
  89: Quantity exceeds limit
  M8: Missing information
  T7: Non-covered days supply

Prescription Service - Coverage verification
Dispense Service - Claim submission
Patient Registry - Insurance member data
Medicine Directory - Drug pricing, NDC codes

Support

UHIS Helpdesk: uhis-support@moh.gov.eg | +20 2 1234 5678
Technical Issues: #insurance-service
Business Hours: Sunday-Thursday, 9 AM - 5 PM
Emergency: 24/7 on-call for claim processing failures

Insurance & Coverage Service ​

Overview ​

Purpose ​

Primary Functions ​

Egypt Healthcare Context ​

Architecture ​

Key Features ​

1. Real-Time Eligibility Verification ​

2. Coverage Determination ​

3. Prior Authorization (PA) ​

4. Copayment Calculation ​

5. Claims Processing ​

6. Coordination of Benefits (COB) ​

API Endpoints ​

Eligibility ​

Coverage Check ​

Prior Authorization ​

Claims ​

Integration Points ​

UHIS Central System ​

Private Insurance APIs ​

Internal Services ​

Performance & Scalability ​

Performance Targets ​

Configuration ​

Business Rules ​

Prior Authorization Criteria ​

Claim Denial Reasons ​

Related Services ​

Support ​

Insurance & Coverage Service

Overview

Purpose

Primary Functions

Egypt Healthcare Context

Architecture

Key Features

1. Real-Time Eligibility Verification

2. Coverage Determination

3. Prior Authorization (PA)

4. Copayment Calculation

5. Claims Processing

6. Coordination of Benefits (COB)

API Endpoints

Eligibility

Coverage Check

Prior Authorization

Claims

Integration Points

UHIS Central System

Private Insurance APIs

Internal Services

Performance & Scalability

Performance Targets

Configuration

Business Rules

Prior Authorization Criteria

Claim Denial Reasons

Related Services

Support