# 835 — Electronic Remittance Advice (005010X221A1)

The 835 transaction set carries payment and remittance information from a
payer (or its clearinghouse) to a provider, in response to previously
submitted 837P claims. Cyclone parses it into a `ParseResult835` and surfaces
the per-claim payment breakdown.

## File format

Same as 837P — ASCII text with the same four delimiters declared in `ISA`.

## Envelope

Same as 837P (`ISA/IEA/GS/GE/ST/SE`).

## Loops

| Loop | Contents |
|---|---|
| 1000A | Payer (N1*PR) |
| 1000B | Payee (N1*PE) |
| 2100 | Claim payment (CLP) |
| 2110 | Service payment (SVC) |

## Header segments

- `BPR` — financial information (credit/debit flag, total paid amount, account details)
- `TRN` — reassociation trace number
- `DTM` — production date

## CLP — claim payment

`CLP01` = payer claim control number; `CLP02` = status code; `CLP03` = total
claim charge; `CLP04` = total claim paid amount.

| CLP02 | Meaning |
|---|---|
| 1 | Processed as Primary |
| 2 | Processed as Secondary |
| 3 | Processed as Tertiary |
| 4 | Denied |
| 19 | Processed as Primary, Forwarded |
| 20 | Processed as Secondary, Forwarded |
| 21 | Reversal of Previous Payment |
| 22 | Reversal of Previous Payment (Secondary) |
| 23 | Not Our Claim, Forwarded |
| 25 | Predetermination Pricing Only - No Payment |

## Validation rules Cyclone enforces

Rules are defined in `cyclone/parsers/validator_835.py` and registered on
`PayerConfig835` for the active payer.

| Rule | Severity | Description |
|---|---|---|
| `R835_BPR01_handling_code_allowed` | error | `BPR01` ∈ `allowed_handling_codes` (e.g. `C`, `D`, `I`, `X`) |
| `R835_BPR02_positive` | error | `BPR02` (paid amount) must be `> 0` |
| `R835_BAL_BPR_vs_CLP04` | error | `BPR02` equals the sum of all `CLP04` (±$0.01) |
| `R835_BAL_CLP04_vs_SVC03` | error | Each `CLP04` equals the sum of its `SVC03` amounts (±$0.01) |
| `R835_CLP01_present` | error | `CLP01` (payer claim control number) is non-empty |
| `R835_CLP02_status_allowed` | error | `CLP02` ∈ `allowed_status_codes` |
| `R835_CLP03_present` | error | `CLP03` (total claim charge) must be `> 0` |
| `R835_PAYER_TAX_ID_matches` | warning | `BPR10` ∈ `expected_payer_tax_ids` |
| `R835_PAYER_HEALTH_PLAN_ID_matches` | warning | `N1*PR N104` matches `expected_payer_health_plan_id` |
| `R835_PAYEE_NPI_format` | error | Payee NPI must be 10 digits |
| `R835_REGN01_trn02_present` | error | `TRN02` (originating company id / payee TPID) is non-empty |

## CAS — claim/service adjustment

`CAS` segments carry reason codes (`CO` contractual obligation, `PR` patient
responsibility, `OA` other adjustments, `PI` payer-initiated reduction).
Cyclone preserves the raw `CAS` text in `raw_segments`; deep-parsing of
reason codes is sub-project 3.

## CO Medicaid specifics

- `BPR10` = `"81-1725341"` (TXIX / Medicaid) or `"84-0644739"` (BHA / behavioral health)
- `N1*PR` `N104` = `"7912900843"` — payer ID (Health Plan ID)
- `N1*PR` `N102` = `"CO_TXIX"` or `"CO_BHA"` — payer name
- Allowed `CLP02` codes: `{1, 2, 3, 4, 19, 20, 21, 22, 23, 25}`

## Reconciliation (sub-project 2)

Matching 835 payouts back to 837P submissions by patient control number +
date of service is deferred to sub-project 2. Cyclone currently stores the
835 output as-is.