docs: add 835 reference note

2026-06-19 19:49:15 -06:00
parent 9fe41b7269
commit 5927636b7b
1 changed files with 86 additions and 0 deletions
@@ -0,0 +1,86 @@
+# 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.