Billing Service — AI Integration
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · ai-gateway-service
1. Posture
Billing treats AI as assistive only. No autonomous pricing, automatic write-offs, or AI-posted payments. All AI calls go through ai-gateway-service via Kong /v1/ai/* — no vendor SDK keys in this service. Assistive outputs are drafts; a human approves before a ledger entry is created.
| Decision | Rationale |
|---|---|
| No direct LLM integration in billing-service | Centralised governance, cost control, HITL enforcement, PII redaction handled by ai-gateway |
| No AI-driven automatic write-offs | Financial integrity; ledger mutations require human authorisation |
| No AI-driven price suggestion | Regulatory exposure (pricing transparency laws); keep price list deterministic |
| AI used for code assist, denial summarisation, collections tone | Proven low-risk productivity gains |
2. Use cases (Tier A only — assistive drafts)
| Use case | Trigger | Prompt template | Output | HITL | Moderation |
|---|---|---|---|---|---|
code_assist.suggest_cpt | Biller opens an uncoded charge | prompts/billing/cpt_assist.v1.md | Top-N CPT/HCPCS/ICHI candidates with confidence + rationale | Biller must pick a code; no auto-apply | Terminology-service membership check server-side |
denial.summarise_reason_codes | Denial case opened | prompts/billing/denial_summary.v1.md | Human-readable summary of payer reason codes + suggested next action | Supervisor reviews | — |
statement.tone_polish | Statement text template authoring | prompts/billing/statement_tone.v1.md | Polished RTL-safe collection letter copy | Tenant admin reviews before publishing template | Profanity + threat filter |
ledger.anomaly_narration | Ops dashboard click-through | prompts/billing/ledger_narrate.v1.md | Plain-language description of ledger pattern | Ops only; no ledger write | — |
3. Call pattern
4. Redaction + context hygiene
| Field | Sent to AI | Transformation |
|---|---|---|
| Patient name | no | stripped |
| Patient identifiers | no | stripped |
| Encounter ID | yes (pseudonymised) | salted hash |
| Clinical note excerpt | yes, ≤ 500 chars, redacted | names → [NAME], dates → [DATE] |
| Amounts / currency | yes (numeric only) | — |
| Tenant ID | yes (pseudonymised) | salted hash for cost attribution |
| Actor ID | no | — |
5. Provenance
Each AI-assisted candidate stored alongside the charge/denial/adjustment carries an ai_provenance blob:
{
"provider": "anthropic",
"model": "claude-haiku-latest",
"promptTemplate": "prompts/billing/cpt_assist.v1",
"promptHash": "sha256:...",
"confidence": 0.83,
"latencyMs": 420,
"requestId": "aig_01J0...",
"acceptedBy": "usr_01J0...",
"acceptedAt": "2026-04-17T10:10:00Z"
}
6. Tenant controls
| Control | Scope | Default |
|---|---|---|
| AI features on/off | tenant | off |
| Per-use case enablement | tenant | off |
| Redaction aggressiveness | tenant | aggressive |
| Daily token budget | tenant | 100 000 |
| Data-residency allowlist | tenant | required |
7. Offline degradation
When ai-gateway is unavailable or the tenant is offline:
- Code-assist UI hides the suggestion panel with banner "Code assist temporarily unavailable; continue coding manually."
- Denial summariser returns the raw reason code list.
- No fallback to external vendor from inside billing.
8. Compliance
- All AI calls are audit-logged (
ai.billing.call.v1via audit-service). - No AI output is persisted as authoritative until a human accepts.
- GDPR: AI calls are classified as processing by a sub-processor; tenant admin consent recorded in tenant-service.
- No AI is used on refund decisions, adjustment approvals, or payment posting (compliance blast-radius).