Skip to main content

​
Overview

Phase 2 adds live clearinghouse connectivity via Waystar REST API, replacing Phase 1 stubs with operational transport for claims submission (837P), remittance retrieval (835), eligibility verification (270/271), and acknowledgment processing (999, 277CA). Architecture Decision: REST-only transport. SFTP is deferred due to Deno Deploy incompatibility with native SSH modules.

​
1. Credential Configuration

​
Edge Function Secrets

Clearinghouse credentials are stored as Edge Function Secrets (environment variables), not in the database. To configure: Supabase Dashboard → Settings → Edge Functions → Secrets

​
Vault Reference Resolution

The pm_clearinghouse_config.credentials_vault_ref column stores a logical reference (e.g., vault://waystar/api-key). At runtime, the edge function resolves this to the corresponding Edge Function Secret.

​
2. Health Monitoring

​
Health Check Endpoint

clearinghouse-health-check runs every 30 minutes (cron) and updates pm_clearinghouse_config:

​
Health Badge UI

The configuration list page displays a ClearinghouseHealthBadge next to each configuration. Colors use semantic tokens (text-success, text-warning, text-destructive).

​
3. Batch Submission Flow

​
Edge Function: clearinghouse-submit

  1. Reads batch from pm_transaction_batches
  2. Generates X12 837P envelope using envelope.ts + generate-837p.ts
  3. Acquires OAuth2 token via rest-transport.ts
  4. Submits to Waystar REST endpoint
  5. Updates batch with trace number and status
  6. Logs transaction to pm_transaction_log

​
Retry Logic

Failed submissions use exponential backoff:
  • Max retries: 3
  • Base delay: 1 second (doubles each retry)
  • Dead letter: After max retries, batch marked as error with transport_error

​
4. ERA Retrieval Flow

​
Edge Function: clearinghouse-retrieve

  1. Fetches pending 835 files from Waystar API
  2. Parses using parse-835.ts
  3. Creates inbound pm_transaction_batches record
  4. Logs each remittance to pm_transaction_log

​
5. X12 Transaction Types

​
6. Permissions

​
7. Troubleshooting

​
Edge Function Logs

  • Submit: Supabase Dashboard → Edge Functions → clearinghouse-submit → Logs
  • Retrieve: Supabase Dashboard → Edge Functions → clearinghouse-retrieve → Logs
  • Health: Supabase Dashboard → Edge Functions → clearinghouse-health-check → Logs

​
References