> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Clearinghouse Transport Administration Guide

> Phase 2 adds live clearinghouse connectivity via Waystar REST API, replacing Phase 1 stubs with operational transport for claims submission (837P), remittance…

## 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.

| Secret Name             | Purpose                                                    |
| ----------------------- | ---------------------------------------------------------- |
| `WAYSTAR_CLIENT_ID`     | OAuth2 client ID for Waystar REST API                      |
| `WAYSTAR_CLIENT_SECRET` | OAuth2 client secret                                       |
| `WAYSTAR_API_ENDPOINT`  | Base URL for Waystar API (e.g., `https://api.waystar.com`) |

**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`:

| Column                 | Description                                   |
| ---------------------- | --------------------------------------------- |
| `health_status`        | `healthy`, `degraded`, `unhealthy`, `unknown` |
| `last_health_check_at` | Timestamp of last check                       |

### 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

| Type  | Direction | Generator/Parser   | Edge Function            |
| ----- | --------- | ------------------ | ------------------------ |
| 837P  | Outbound  | `generate-837p.ts` | `clearinghouse-submit`   |
| 835   | Inbound   | `parse-835.ts`     | `clearinghouse-retrieve` |
| 270   | Outbound  | `generate-270.ts`  | (Future)                 |
| 271   | Inbound   | `parse-271.ts`     | (Future)                 |
| 999   | Inbound   | `parse-999.ts`     | `clearinghouse-retrieve` |
| 277CA | Inbound   | `parse-277ca.ts`   | `clearinghouse-retrieve` |

***

## 6. Permissions

| Permission Key           | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `pm.clearinghouse.view`  | View configurations, batches, transactions      |
| `pm.clearinghouse.admin` | Create/edit configurations, trigger submissions |

***

## 7. Troubleshooting

| Issue                        | Solution                                                         |
| ---------------------------- | ---------------------------------------------------------------- |
| Health badge shows "Unknown" | Health check hasn't run yet or config is new                     |
| Batch stuck in "submitted"   | Check `transport_error` column; verify secrets                   |
| OAuth2 token failure         | Verify `WAYSTAR_CLIENT_ID` and `WAYSTAR_CLIENT_SECRET` secrets   |
| 999 rejection                | Check `pm_transaction_log` for error codes; correct and resubmit |

### 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

* [PM-15 Phase 1 Admin Guide](/pm/clearinghouse-admin-guide)
* [PM-15-P2 Spec](https://github.com/Encore-OS/encoreos/blob/development/specs/pm/contexts/PM-15-PHASE-2-EXPANSION.md)
* [X12 EDI Technical Design](/architecture/standards/X12-EDI-TECHNICAL-DESIGN)