Configure a new payer in master

Outcome

A new payer exists in rcm_master.payer, has its supported transactions declared in payer_submission_capability, is linked to a trading partner, and has at least one submission_routing_rule so the EDI Gateway can resolve outbound traffic.

This chapter is the master-side payer setup — the platform-wide registry shared by every tenant. Tenant-side overlays (contract, fee schedule, program config) live in Onboarding a payer + program config.

Prerequisites

• PLATFORM_ADMIN (master writes).
• Payer's electronic ID, supported transaction types, filing-deadline policy.
• Trading-partner connection details (SFTP host or REST endpoint).

Flow

Steps

1. Insert the payer row in rcm_master.payer.

   INSERT INTO rcm_master.payer (
     name, short_name, payer_code, payer_type, state,
     electronic_payer_id, is_active
   ) VALUES (
     'Example Medicaid', 'EX-MCD', 'EXMCD', 'MEDICAID_FFS', 'EX',
     'EXMCD001', true
   );

   Column	Notes
   payer_code	Short uppercase identifier; appears in routing rules.
   payer_type	MEDICAID_FFS, MEDICAID_MCO, COMMERCIAL, etc. Drives payer-priority logic (COB ordering).
   electronic_payer_id	Payer ID at the clearinghouse (CMS, Availity, Office Ally).
   state	Two-letter abbreviation; used by routing rules for state-specific Medicaid.

2. Create or link a trading partner in rcm_master.trading_partner.

   INSERT INTO rcm_master.trading_partner (
     name, partner_type, partner_code, connection_config, is_active
   ) VALUES (
     'Example State MMIS', 'STATE', 'EX_MMIS',
     '{"protocol": "SFTP", "host": "sftp.example.gov", "port": 22,
       "username": "rcm_user", "remotePath": "/inbound"}',
     true
   );

   connection_config carries non-secret connection metadata only. Credentials live in Key Vault and are managed via the trading partner credential vault UI.

3. Add submission capabilities for every transaction type the payer supports. Filing deadline is captured per tx type because some payers carry different windows for 837P vs 837I.

   INSERT INTO rcm_master.payer_submission_capability (
     payer_id, tx_type, filing_deadline_days, is_electronic, is_active
   ) VALUES
     ('<payer_id>', '837P', 365, true, true),
     ('<payer_id>', '270', NULL, true, true),
     ('<payer_id>', '278', NULL, true, true);

   Filing deadline NULL is meaningful for tx types where filing windows don't apply (270 eligibility, 278 auth).

4. Add a companion guide if the payer has one. See Add a state companion guide — most state Medicaid programs need it; commercial payers often run on the standard implementation guide and skip this step.

5. Add at least one routing rule so the EDI Gateway has a path to dispatch. Use the Routing Rules UI, or for a one-off:

   INSERT INTO rcm_master.submission_routing_rule (
     state, payer_id, claim_type, tx_type,
     trading_partner_id, companion_guide_id,
     priority, effective_from, is_active
   ) VALUES (
     'EX', '<payer_id>', 'P', '837P',
     '<trading_partner_id>', '<companion_guide_id>',
     50, CURRENT_DATE, true
   );

   Convention: priority=10 for state-pinned, 50 for payer-type, 100 for wildcard fallback.

6. (Medicaid only) Add rate codes in rcm_master.state_rate_code if the state requires custom rate codes per service:

   INSERT INTO rcm_master.state_rate_code (
     state, rate_code, description, service_category,
     unit_type, effective_from, is_active
   ) VALUES ('EX', 'H2019', 'Therapeutic behavioral services', 'ABA', '15MIN',
             '2024-01-01', true);

7. Verify routing resolution from the EDI Gateway:

   curl -X POST http://localhost:3011/edi/routing/resolve \
     -H "Content-Type: application/json" \
     -d '{"payerId":"<payer_id>","state":"EX","claimType":"P","txType":"837P"}'

   Or use the Routing Rules UI simulator for a richer view of which rules competed.

Validation

Check	Expected
rcm_master.payer row	exists, is_active=true
rcm_master.payer_submission_capability rows	one per supported tx_type
rcm_master.trading_partner link	exists, is_active=true
Routing simulator for the new payer	resolves to the expected partner + guide
Test 270 → 271 round trip	succeeds (where applicable)

Troubleshooting

Symptom	Cause	Fix
Routing resolver returns no_route_found	No rule matches the claim shape	Inspect simulator candidates; tighten or add a rule.
837 generation fails with "trading partner inactive"	trading_partner.is_active=false or its credentials purged	Re-activate; re-rotate credentials via Trading partner credential vault.
Filing-deadline alerts fire incorrectly	filing_deadline_days set on a tx type that shouldn't have one (270/278)	UPDATE to NULL; re-check timely-filing query in Reporting.
Customer's 837P missing payer-specific overrides	Companion guide not linked	Set submission_routing_rule.companion_guide_id.

Cross-references

• Tenant-side overlay (contract, fee schedule, program config): Onboarding a payer + program config
• Routing rules detail: Submission routing rules
• Companion guides authoring: Companion guide editor
• Credential rotation: Trading partner credential vault

Next

2.2 — Add a state companion guide