Clearinghouse Multi-Vendor Failover — Admin Guide

​

Overview

​

Prerequisites

• At least one active clearinghouse configuration (see Clearinghouse Admin Guide).
• Executed Business Associate Agreement (BAA) on file for every vendor you intend to enable. Availity and Change Healthcare routes are gated until the BAA toggle is checked.
• pm.clearinghouse.admin permission on the active organization.

​

1. Configure Failover Thresholds

1. Select Primary Vendor (defaults to your existing Waystar config).
2. Select Secondary Vendor. The dropdown only lists vendors with a stored config; vendors without a signed BAA appear disabled with a “BAA required” badge.
3. Acknowledge the BAA on file checkbox for the secondary vendor. Without acknowledgement the Save button stays disabled.
4. Set the failover thresholds:
   • Health check interval (seconds) — how often the router polls vendor health (default 60).
   • Consecutive failures before failover (default 3) — number of failed health checks or transaction errors that flip routing to the secondary.
   • Recovery cool-down (seconds, default 300) — minimum time the primary must remain healthy before traffic flips back.
   • Per-transaction timeout (ms, default 15000) — used by the router to mark a single 837/270/276/278 call as failed.
5. Click Save. Settings are written to pm_clearinghouse_failover_settings scoped to the active organization_id.

The router (resolveVendorRoute / resolveVendorRouteWithAudit in src/cores/pm/services/clearinghouse) reads these thresholds on each routing decision; no redeploy is required.

​

2. Override Routing per Payer

1. Click Add Payer Route.
2. Choose the payer (PM-02 record).
3. Select the Forced Vendor. Only vendors with a config + signed BAA appear.
4. Optional: toggle Allow failover for this payer. When off, the router will surface a hard error instead of falling back if the forced vendor is degraded — useful for payers that reject claims submitted via an unenrolled CH.
5. Save. The row is written to pm_clearinghouse_payer_routes and takes effect on the next routing decision.

1. Per-payer route with allow_failover = false → hard pin.
2. Per-payer route with allow_failover = true → forced vendor with secondary fallback.
3. Global primary → secondary failover.

​

3. Verify Behavior in Supabase

​

3.1 Confirm settings persisted

select primary_vendor, secondary_vendor, failure_threshold,
       recovery_cooldown_seconds, transaction_timeout_ms, baa_acknowledged_at
from pm_clearinghouse_failover_settings
where organization_id = :org_id;

​

3.2 List active payer overrides

select p.name as payer, r.forced_vendor, r.allow_failover, r.updated_at
from pm_clearinghouse_payer_routes r
join pm_payers p on p.id = r.payer_id
where r.organization_id = :org_id
order by p.name;

​

3.3 Trigger a failover and watch the audit log

1. In Failover Settings, temporarily set the primary vendor’s stored credential to an invalid value (or use the Simulate health failure button if your environment exposes it).
2. Submit a test 270 eligibility check from PM-02 against any payer that uses the global route.
3. Within failure_threshold * health_check_interval seconds the router flips to the secondary. Confirm with:

select created_at, action, old_values, new_values
from pm_audit_log
where organization_id = :org_id
  and action = 'clearinghouse_route_failover'
order by created_at desc
limit 10;

​

3.4 Confirm recovery

​

3.5 RLS spot-check

npm run test:rls -- pm-clearinghouse-failover

​

4. Troubleshooting

​

5. Change Log