cyclone/docs/reference/co-medicaid.md

Colorado Medicaid — payer specifics

Cyclone's CO Medicaid (PayerConfig.co_medicaid() and PayerConfig835.co_medicaid_835()) factories encode the trading-partner and code-set rules that the Colorado Department of Health Care Policy & Financing (HCPF) requires.

Trading Partner IDs (TPID)

Role	837P	835
Sender	SKCO0	(varies; usually the clearinghouse)
Receiver	COHCPF	(varies)

These appear in the NM1*PR (payer) and NM1*40 (receiver) segments of the 837P file.

Payer IDs

837P (claims)

• NM1*PR N104 = "SKCO0" (COHCPF)

835 (remittance)

• BPR10 = "81-1725341" — TXIX (Medicaid) account
• BPR10 = "84-0644739" — BHA (behavioral health) account
• N1*PR N104 = "7912900843" — payer ID
• N1*PR N102 is one of "CO_TXIX" or "CO_BHA"

Allowed codes

837P CLM05-3 (frequency code)

Code	Meaning
1	Original claim
7	Replacement claim
8	Void / cancel

Cyclone raises R030_frequency_allowed if any other value appears.

835 CLP02 (claim status code)

Allowed: {1, 2, 3, 4, 19, 20, 21, 22, 23, 25}. See the 835 reference note for the meaning of each.

Place of service (POS)

All CMS POS codes 01–99 are accepted. The canonical list lives in cyclone/parsers/payer.py as CMS_PLACE_OF_SERVICE_CODES and is the source of truth for validation and any UI dropdowns.

Validation rules Cyclone enforces

See 837p.md and the cyclone.parsers.validator / cyclone.parsers.validator_835 modules.

Adding a new payer

The pattern is:

1. Add a PayerConfig (837P) and PayerConfig835 (835) factory in cyclone/parsers/payer.py — usually thin wrappers that override only the differing fields (allowed codes, payer IDs).
2. Register the factory in the PAYER_FACTORIES / PAYER_FACTORIES_835 dicts in cyclone/api.py and cyclone/cli.py.
3. Add a smoke fixture under backend/tests/fixtures/ (a real or synthetic file matching the new payer's rules) and a parser test that loads it.
4. Update this note + the 837p/835 notes with the new payer's specifics.