Finance Portal

Note: The Finance Portal is intentionally isolated from the Admin and Compliance portals. A finance_analyst JWT cannot access platform ops routes (rate tables, programs, rules) or compliance data (producer licensing, filings).

​

URL & Access

​

Sign In

GET https://auth-dev.openinsure.dev/api/auth/sign-in/microsoft
    ?callbackURL=https://finance.openinsure.dev/api/auth/callback

​

Roles & Authorization

​

Navigation

​

Pages

​

Dashboard (/)

• Period toggle — YTD / MTD / QTD links (?period=ytd URL param), default ytd
• KPICard for GWP (Gross Written Premium) — neutral status
• KPICard for AR Outstanding — status='warn' if balance > 0
• KPICard for Loss Ratio — status='warn' if > 65%, status='critical' if > 85%
• Navigation links to A/R Aging, Pipeline, and Financials

• Fixed header with total outstanding balance
• CSS horizontal bar chart — 5 aging buckets (Current / 31–60 / 61–90 / 91–120 / 120+), bars sized relative to the largest bucket, no chart library
• Top 5 overdue accounts mini-table — Invoice #, Insured, Outstanding (cents), Days overdue
  • > 90d → red, > 30d → amber, else muted
  • “View all N invoices →” link to full AR Aging report

• TanStack Query polling (refetchInterval: 60_000) with initialData from server render
• Groups entries by dunning stage: Stage 3 Critical (red) first, Stage 2 Warning (amber) next
• Each card shows policy number, insured name, amount due, and days remaining on grace period
• Clicking a card opens a shadcn Dialog with amount due, grace period end, dunning stage, and optional note input
• If queue empty: green checkmark (“Queue is clear”)
• “Full A/R Aging Report” link at bottom

• GET /v1/analytics/mga?period=${period} — GWP + loss ratio
• GET /v1/reports/ar-aging — bucket bars + top 5 overdue rows (amounts in cents)
• GET /v1/billing/non-pay-queue — non-pay entries for right pane (amountDue in dollars)

​

AR Aging (/reports/ar-aging)

​

Financials (/reports/financials)

​

Reconciliation (/reports/reconciliation)

​

Statutory (/reports/statutory)

​

Chart of Accounts (/reports/chart-of-accounts)

​

Trial Balance & Journal Entries

• Trial Balance (getTrialBalance()) — Queries all 9 account types concurrently via Promise.all. Each row contains the account ID, account type code (1-9), human-readable name, total credits, total debits, and net balance — all in integer cents. Returns a balanced flag confirming debits equal credits across the organization’s subledger.

  Code	Account Name
  1	Carrier Payable
  2	MGA Fiduciary
  3	MGA Revenue
  4	Producer Payable
  5	Tax Authority Payable
  6	Loss Fund
  7	Claims Paid
  8	Reserves
  9	Reinsurer Payable

• Journal Entries (getJournalEntries()) — Filtered transfer history through the MGA fiduciary hub account. Supports from/to date-range filtering (converted to TigerBeetle nanosecond timestamps) and a limit parameter (default 100). Each entry includes the transfer ID, debit/credit account IDs, amount in cents, transfer code, and timestamp.

​

Report Builder (/reports/builder)

​

API Proxy Allowlist

GET  /v1/analytics/entities
GET  /v1/analytics/pipeline
GET  /v1/analytics/captive
GET  /v1/reports/ar-aging
GET  /v1/reports/statutory
GET  /v1/reports/financials
GET  /v1/reports/reconciliation
PATCH /v1/reports/reconciliation/:id
GET  /v1/reports/chart-of-accounts
GET  /v1/reports/builder
POST /v1/reports/builder
GET  /v1/billing/non-pay-queue
GET  /v1/ledger/accounts
GET  /v1/ledger/transfers
GET  /v1/ledger/trial-balance
GET  /v1/ledger/journal-entries
GET  /v1/ledger/lookup-transfers
GET  /v1/ledger/:orgId/transfers

​

Environment Variables

# Set the JWT secret (production)
wrangler secret put FINANCE_JWT_SECRET --name oi-sys-finance

# Local dev (.env.local)
FINANCE_JWT_SECRET=9d79c38aa7d57bd24a1afe213848b2b935519afb08a3923ac112aed71fd5bc21
API_URL=http://localhost:8787
DEMO_MODE=true

​

Deployment

# Build + deploy
cd apps/finance-portal
npx opennextjs-cloudflare deploy -- --keep-vars

# Or via pnpm filter
pnpm --filter @openinsure/finance-portal deploy

​

Period Close Workflow

​

Close Lifecycle

open  -->  pending_review  -->  closed
  |                                 |
  └─────────  reopened  ◄───────────┘

​

Creating a Period Close

POST /v1/period-close
Authorization: Bearer <token>
Content-Type: application/json

{
  "period": "2025-06"
}

​

Default Checklist

​

Updating Checklist Items

PATCH /v1/period-close/:id/items/:itemId
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "completed",
  "notes": "Reconciled against GL. No variances."
}

​

Progress Tracking

GET /v1/period-close/:id
Authorization: Bearer <token>

• Total items, completed count, and completion percentage
• Breakdown by category
• List of blocked items

​

Accrual Entries

POST /v1/period-close/:id/accruals
Authorization: Bearer <token>
Content-Type: application/json

{
  "expenses": [
    { "category": "legal", "amount": 12000, "accountCode": "6100" },
    { "category": "claims_adjustment", "amount": 8500 }
  ],
  "losses": {
    "estimatedIBNR": 285000,
    "estimatedULAE": 42000
  }
}

​

Reversing Accruals

POST /v1/period-close/:id/reverse-accruals
Authorization: Bearer <token>
Content-Type: application/json

{
  "accrualResult": { "..." }
}

​

Initiating Close

POST /v1/period-close/:id/initiate
Authorization: Bearer <token>

​

Dual-Control Approval

POST /v1/period-close/:id/approve
Authorization: Bearer <token>

​

Reconciliation

​

Upload Carrier Statement

POST /v1/reconciliation/upload
Authorization: Bearer <token>
Content-Type: application/json

{
  "carrierName": "National General Insurance",
  "statementDate": "2025-06-30",
  "rows": [
    { "policyNumber": "MHC-CA-2025-001", "premium": 12500, "insuredName": "Acme Corp" },
    { "policyNumber": "MHC-FL-2025-042", "premium": 8750 }
  ]
}

POST /v1/reconciliation/upload-csv
Content-Type: multipart/form-data

carrierName=National General Insurance
statementDate=2025-06-30
file=@carrier-statement.csv

​

Auto-Matching Logic

1. Exact match — Policy number matches (case-insensitive) and premium amounts agree within $0.01.
2. Discrepancy — Policy number matches but premium amounts differ.
3. Unmatched carrier — Carrier row has no corresponding system policy.
4. Unmatched system — System policy has no corresponding carrier row.

​

Session Management

GET /v1/reconciliation/sessions
Authorization: Bearer <token>

GET /v1/reconciliation/sessions/:id
Authorization: Bearer <token>

​

Manual Override

PATCH /v1/reconciliation/rows/:id/override
Authorization: Bearer <token>
Content-Type: application/json

{
  "overrideStatus": "accepted",
  "overrideNote": "Premium difference due to mid-term endorsement not yet on carrier statement"
}

​

Compliance Portal

​

Authentication