Skip to main content

​
Overview

The Clearinghouse module enables your organization to connect to ANSI X12 clearinghouses for electronic claims submission (837P/I), remittance retrieval (835), eligibility verification (270/271), claim status inquiries (276/277), and prior authorization requests (278). Phase 1 provides configuration management, batch tracking, transaction logging, and payer enrollment. Actual clearinghouse transport (Waystar REST/SFTP) is planned for Phase 2.

​
Prerequisites

  • Organization Admin or Billing Manager role with pm.clearinghouse.admin permission
  • Active payer records in PM-02 (Insurance & Eligibility)
  • Clearinghouse vendor contract (e.g., Waystar) with credentials

​
1. Configuring a Clearinghouse Connection

Practice Management → Clearinghouse → Configurations

​
Add New Configuration

  1. Click Add Configuration
  2. Fill required fields:
    • Clearinghouse Name — Display name (e.g., “Waystar Production”)
    • Provider — Select from supported providers (currently: Waystar)
    • Connection Type — API or SFTP
    • Sender ID — Your organization’s sender identifier
    • Receiver ID — Clearinghouse receiver identifier
  3. For API connections:
    • API Endpoint — Full URL provided by clearinghouse
    • Credentials Vault Ref — Vault reference for API key/token (e.g., vault://waystar/api-key)
  4. For SFTP connections:
    • Host — SFTP server hostname
    • Port — SFTP port (default: 22)
    • Submission Path — Remote directory for outbound files
    • Retrieval Path — Remote directory for inbound files (835s)
    • Username Vault Ref — Vault reference for SFTP username
    • Credentials Vault Ref — Vault reference for SFTP password/key
  5. Click Save

​
Vault References

Credentials are never stored in the database. Instead, the configuration stores a vault reference string that is resolved at runtime by the edge function. Format: vault://{provider}/{key-name} Examples:
  • vault://waystar/api-key — Waystar API key
  • vault://waystar/sftp-password — Waystar SFTP password
To add credentials, go to Settings → Cloud → Secrets and add the secret with the corresponding name.

​
2. Payer Enrollment

Before submitting claims through a clearinghouse, each payer must be enrolled. Practice Management → Clearinghouse → Enrollments

​
Add Enrollment

  1. Click Add Enrollment
  2. Select:
    • Clearinghouse — The configuration to enroll with
    • Payer — The insurance payer
    • Transaction Types — Which X12 transactions are enabled (837P, 837I, 835, 270/271, etc.)
  3. Set Enrollment Status (pending, active, suspended, terminated)
  4. Fill optional dates: Enrolled Date, Effective Date, Termination Date
  5. Click Save

​
Enrollment Statuses

​
3. Transaction Batches

Batches group related X12 transactions for submission or retrieval. Practice Management → Clearinghouse → Batches

​
Batch Lifecycle

​
Viewing Batch Details

Click any batch row to see:
  • Transaction type, direction, record count
  • Submission timestamp and response data
  • Error details (if rejected)
  • File name and size

​
4. Transaction Log

The transaction log is an append-only audit trail of all clearinghouse interactions. Practice Management → Clearinghouse → Transactions

​
Key Fields

  • Trace Number — Unique identifier for tracking
  • Transaction Type — X12 type (837P, 835, etc.)
  • Direction — Inbound or outbound
  • Status — Current processing status
  • Claim ID — Associated claim (if applicable)
Note: Transaction log entries cannot be edited or deleted. This ensures audit integrity for HIPAA compliance.

​
5. Security Considerations

​
Credential Storage

  • All credentials use vault references — never stored in the database
  • Edge functions resolve vault refs at runtime
  • Rotate credentials regularly through your vault provider

​
Audit Trail

  • All configuration changes are tracked via created_by/updated_by
  • Transaction log is immutable (append-only, no UPDATE/DELETE)
  • Batch status changes are timestamped

​
PHI Protection

  • X12 transactions contain PHI (patient demographics, diagnoses)
  • All transport uses TLS encryption
  • Log entries do not store claim content — only trace numbers and status

​
Multi-Tenant Isolation

  • All clearinghouse data is scoped by organization_id
  • Row-Level Security (RLS) with FORCE prevents cross-tenant access
  • DELETE operations restricted to org_admin role

​
6. Troubleshooting

​
Common Issues

​
Edge Function Logs

Check the clearinghouse-batch-submit function logs: Supabase Dashboard → Edge Functions → clearinghouse-batch-submit → Logs

​
7. Phase 2 Roadmap

Phase 2 will implement:
  • Live Waystar REST API connectivity
  • SFTP file transfer for 837P/I submission and 835 retrieval
  • Real-time eligibility checks (270/271)
  • Claim status inquiries (276/277)
  • Prior authorization requests (278)
  • Automated ERA processing and payment posting

​
References