# 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](./837p.md#validation-rules-cyclone-enforces) 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.