HMO Plan Provider Guide

This guide explains exactly how HMO providers integrate with the platform to discover, sell, validate coverage, approve care, and manage insured users — based on current live platform behavior.

Your Role as an HMO Provider

You provide health insurance coverage and benefit authorization. The platform:

Discovers your approved HMO plans
Allows users to compare and purchase your plans
Verifies a user’s coverage and benefits in real time
Requests approvals for consultations or treatments
Expects signed, timely responses from your system
Uses your responses to complete booking and payment flows

Prerequisites (Platform-Side Setup)

Before you can receive events:

Requirement	Details
Business Record	Must exist with status: ACTIVE
Service Offering	One or more APPROVED offerings in category `hmo_plan`
Callback URLs	`testCallbackUrl` and `productionCallbackUrl` must be set
API Keys	Test and/or Production keys issued via platform admin
Bank Verification	Required for production keys

Note: Callback URLs cannot be set via API. They are configured by the platform team.

Environments

Environment	Triggered When	Uses
Test	Test keys generated	`testCallbackUrl` + test API key
Production	Account is live	`productionCallbackUrl` + production API key

Security: HMAC SHA256 Signatures

All communication is secured using HMAC SHA256 with your environment-specific secret.

From Platform → You (Inbound)

Header	Value
X-Event-Id	Unique event UUID
X-Timestamp	Unix seconds
X-Signature	`HMAC_SHA256( sha256(body) + "\n" + timestamp, secret )`
Content-Type	application/json

From You → Platform (Outbound)

Endpoint
POST /api/partners/:partnerId/callback

Header	Value
x-timestamp	Unix seconds
x-signature	HMAC SHA256 signature
Content-Type	application/json

Clock skew allowed: ±5 minutes

Signature Generation (Node.js Example)

import crypto from "crypto";

function signPayload(body: any, secret: string, timestamp: number): string {
  const bodyHash = crypto
    .createHash("sha256")
    .update(JSON.stringify(body))
    .digest("hex");

  const canonical = `${bodyHash}\n${timestamp}`;
  return crypto.createHmac("sha256", secret).update(canonical).digest("hex");
}

Use Case: Finding & Buying an HMO Plan

This section covers discovery, comparison, and purchase of HMO plans (before any consultation happens).

HMO Plan Discovery & Purchase Flow (High Level)

User searches for available HMO plans
Platform queries HMO partners for plan listings
User compares plans (price, coverage, benefits)
User selects a plan
Platform sends purchase request to HMO
HMO confirms activation
Coverage becomes available for consultations

Events You Will Receive (Plan Discovery & Purchase)

1. `hmo.plan.search`

Sent when a user searches for HMO plans.

Payload

{
  "event_id": "evt-401",
  "event_type": "hmo.plan.search",
  "timestamp": "2025-11-05T08:30:00Z",
  "user": { "id": "usr-789" },
  "context": {
    "filters": {
      "coverage_type": "individual",
      "location": "Lagos",
      "max_budget": 50000,
      "service_types": ["consultation", "lab"]
    }
  },
  "meta": {
    "search_id": "srch-001",
    "trace_id": "trace-101"
  }
}

Your Response

{
  "status": "success",
  "search_id": "srch-001",
  "plans": [
    {
      "plan_code": "BASIC_PLUS",
      "name": "Basic Plus Plan",
      "coverage_type": "individual",
      "pricing": {
        "amount": 30000,
        "currency": "NGN",
        "billing_cycle": "monthly"
      },
      "benefits": {
        "consultations_per_year": 10,
        "labs_covered": true,
        "hospital_network": "standard"
      },
      "waiting_period_days": 0
    }
  ]
}

2. `hmo.plan.details.request`

Sent when a user views a specific plan.

Payload

{
  "event_id": "evt-402",
  "event_type": "hmo.plan.details.request",
  "timestamp": "2025-11-05T08:45:00Z",
  "context": {
    "plan_code": "BASIC_PLUS"
  },
  "meta": { "request_id": "plan-req-123" }
}

Your Response

{
  "status": "success",
  "plan": {
    "plan_code": "BASIC_PLUS",
    "name": "Basic Plus Plan",
    "description": "Entry-level health coverage for individuals.",
    "pricing": {
      "amount": 30000,
      "currency": "NGN",
      "billing_cycle": "monthly"
    },
    "benefits": {
      "consultations_per_year": 10,
      "labs_covered": true,
      "drugs_covered": false
    },
    "exclusions": ["surgery", "maternity"],
    "waiting_period_days": 0
  }
}

3. `hmo.plan.purchase.request`

Sent when a user proceeds to buy a plan.
Note: Pricing is required for order creation.

Payload

{
  "event_id": "evt-403",
  "event_type": "hmo.plan.purchase.request",
  "timestamp": "2025-11-05T09:10:00Z",
  "user": {
    "id": "usr-789",
    "name": "John Ade"
  },
  "context": {
    "plan_code": "BASIC_PLUS",
    "beneficiary": {
      "type": "self",
      "dob": "1995-03-12"
    }
  },
  "meta": {
    "purchase_id": "pur-555"
  }
}

Your Response

{
  "status": "initiated",
  "purchase_id": "pur-555",
  "initiated_at": "2025-11-05T09:10:05Z",
  "pricing": {
    "amount": 30000,
    "currency": "NGN",
    "billing_cycle": "monthly"
  }
}

4. `hmo.plan.purchase.confirmed`

Sent after payment succeeds.

Payload

{
  "event_id": "evt-404",
  "event_type": "hmo.plan.purchase.confirmed",
  "timestamp": "2025-11-05T09:12:00Z",
  "context": {
    "purchase_id": "pur-555",
    "plan_code": "BASIC_PLUS",
    "member": {
      "member_id": "HMO-99881"
    }
  }
}

Your Response

{
  "status": "acknowledged",
  "acknowledged_at": "2025-11-05T09:12:03Z"
}

Events You Will Receive (Coverage & Authorization – Post-Purchase)

1. `hmo.coverage.verify`

Sent when a user selects an HMO plan or attempts to use insurance.

Payload

{
  "event_id": "evt-101",
  "event_type": "hmo.coverage.verify",
  "timestamp": "2025-11-05T09:00:00Z",
  "user": {
    "id": "usr-123",
    "name": "Jane Doe"
  },
  "context": {
    "member": {
      "member_id": "HMO-99881",
      "plan_code": "BASIC_PLUS"
    },
    "service": {
      "type": "consultation",
      "specialty": "general_practitioner"
    }
  },
  "meta": {
    "verification_id": "ver-456",
    "trace_id": "trace-001"
  }
}

Your Response

{
  "status": "covered",
  "verification_id": "ver-456",
  "covered_at": "2025-11-05T09:00:05Z",
  "benefits": {
    "coverage_percent": 100,
    "copay": { "amount": 0, "currency": "NGN" },
    "limits": {
      "visits_remaining": 5
    }
  }
}

2. `hmo.authorization.request`

Sent when approval is required before proceeding.

Payload

{
  "event_id": "evt-202",
  "event_type": "hmo.authorization.request",
  "timestamp": "2025-11-05T10:30:00Z",
  "user": { "id": "usr-123", "name": "Jane Doe" },
  "context": {
    "member": {
      "member_id": "HMO-99881",
      "plan_code": "BASIC_PLUS"
    },
    "service": {
      "type": "consultation",
      "specialty": "general_practitioner",
      "estimated_cost": { "amount": 5000, "currency": "NGN" }
    }
  },
  "meta": { "authorization_id": "auth-789" }
}

Your Response

{
  "status": "approved",
  "authorization_id": "auth-789",
  "approved_at": "2025-11-05T10:30:08Z",
  "coverage": {
    "approved_amount": { "amount": 5000, "currency": "NGN" },
    "copay": { "amount": 0, "currency": "NGN" }
  }
}

3. `hmo.claim.notification`

Sent after service delivery for record/claim tracking.

Payload

{
  "event_id": "evt-303",
  "event_type": "hmo.claim.notification",
  "timestamp": "2025-11-05T15:00:00Z",
  "context": {
    "claim": {
      "claim_id": "clm-001",
      "member_id": "HMO-99881",
      "service": "consultation",
      "amount": { "amount": 5000, "currency": "NGN" }
    }
  }
}

Your Response

{
  "status": "acknowledged",
  "acknowledged_at": "2025-11-05T15:00:04Z"
}

Events You Must Send (via Callback)

Plan Purchase Lifecycle

hmo.plan.activated
When coverage becomes active.

{
  "event_id": "evt-your-401",
  "event_type": "hmo.plan.activated",
  "timestamp": "2025-11-05T09:13:00Z",
  "context": {
    "member_id": "HMO-99881",
    "plan_code": "BASIC_PLUS",
    "start_date": "2025-11-05",
    "end_date": "2026-11-04"
  }
}

hmo.plan.cancelled
If a plan is cancelled or expires.

{
  "event_id": "evt-your-402",
  "event_type": "hmo.plan.cancelled",
  "timestamp": "2025-12-01T10:00:00Z",
  "context": {
    "member_id": "HMO-99881",
    "plan_code": "BASIC_PLUS",
    "reason": "user_requested"
  }
}

Coverage & Authorization Lifecycle

hmo.coverage.updated
When a member’s plan or benefits change.

{
  "event_id": "evt-your-001",
  "event_type": "hmo.coverage.updated",
  "timestamp": "2025-11-06T09:00:00Z",
  "context": {
    "member_id": "HMO-99881",
    "plan_code": "PREMIUM",
    "effective_date": "2025-11-06"
  }
}

hmo.authorization.revoked
If an approval is later invalidated.

{
  "event_id": "evt-your-002",
  "event_type": "hmo.authorization.revoked",
  "timestamp": "2025-11-06T11:00:00Z",
  "context": {
    "authorization_id": "auth-789",
    "reason": "Policy limit exceeded"
  }
}

Platform responds with:

{ "status": "acknowledged" }

Key Notes

Topic	Detail
Plan Codes	Must match approved offerings / approved plan identifiers
Billing Cycles	monthly or annual
Waiting Period	Enforced after activation if > 0
Currency	Always use "currency" field (typically "NGN")
SLA	Aim for <10s response time for search, purchase, verify & auth
Activation	No coverage until `hmo.plan.activated`
Missing Callback URL	You will be skipped entirely

Testing Checklist

Confirm testCallbackUrl is reachable
Request test API keys
Implement:
- Signature verification (inbound)
- Signature generation (outbound)
- JSON validation
Respond to:
- hmo.plan.search
- hmo.plan.details.request
- hmo.plan.purchase.request
- hmo.plan.purchase.confirmed
- hmo.coverage.verify
- hmo.authorization.request
- hmo.claim.notification
Send:
- hmo.plan.activated
- hmo.plan.cancelled
- hmo.coverage.updated
- hmo.authorization.revoked
Run end-to-end tests with platform team

Summary – Full HMO Plan Lifecycle

Plan discovery → hmo.plan.search
Plan comparison → hmo.plan.details.request
Purchase → hmo.plan.purchase.request → hmo.plan.purchase.confirmed
Activation → hmo.plan.activated
Coverage check → hmo.coverage.verify
Service approval → hmo.authorization.request
Service delivery → hmo.claim.notification
Changes / cancellations → hmo.coverage.updated / hmo.plan.cancelled / hmo.authorization.revoked

✅ This completes the Find → Buy → Verify → Use → Manage HMO plan lifecycle.

Need Help?
Contact the platform integrations team with:

Your partnerId
Environment (test/production)
Signature or payload logs

You’re now ready to support insured users through full HMO plan integration.

HMO Plan Provider Guide

Your Role as an HMO Provider

Prerequisites (Platform-Side Setup)

Environments

Security: HMAC SHA256 Signatures

From Platform → You (Inbound)

From You → Platform (Outbound)

Signature Generation (Node.js Example)

Use Case: Finding & Buying an HMO Plan

HMO Plan Discovery & Purchase Flow (High Level)

Events You Will Receive (Plan Discovery & Purchase)

1. hmo.plan.search

2. hmo.plan.details.request

3. hmo.plan.purchase.request

4. hmo.plan.purchase.confirmed

Events You Will Receive (Coverage & Authorization – Post-Purchase)

1. hmo.coverage.verify

2. hmo.authorization.request

3. hmo.claim.notification

Events You Must Send (via Callback)

Plan Purchase Lifecycle

Coverage & Authorization Lifecycle

Key Notes

Testing Checklist

Summary – Full HMO Plan Lifecycle

1. `hmo.plan.search`

2. `hmo.plan.details.request`

3. `hmo.plan.purchase.request`

4. `hmo.plan.purchase.confirmed`

1. `hmo.coverage.verify`

2. `hmo.authorization.request`

3. `hmo.claim.notification`