Skip to main content

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
    );
    ColumnNotes
    payer_codeShort uppercase identifier; appears in routing rules.
    payer_typeMEDICAID_FFS, MEDICAID_MCO, COMMERCIAL, etc. Drives payer-priority logic (COB ordering).
    electronic_payer_idPayer ID at the clearinghouse (CMS, Availity, Office Ally).
    stateTwo-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 in the platform console: open Master data → Payers, click the payer's row, and go to the Submission tab (/master-data/payers/<payer_id>?tab=submission). Add one capability for each way the payer takes claims — one per claim type (Professional 837P or Institutional 837I) and submission method (EDI, Portal, Paper or API).

    1. Click Add submission capability.
    2. Pick the Claim type and Submission method.
    3. Pick the Trading partner the claims go through (optional; leave it on (none) for a portal or paper route). The list is rcm_master.trading_partner — create the partner first (step 2).
    4. Enter Timely filing days: days from the date of service to the last day a claim can be submitted. Leave it blank when the payer's window is not tracked. A payer with different windows for 837P and 837I gets one capability per claim type, each with its own number.
    5. Tick Accepts secondary claims and Accepts corrected claims where the payer takes them, add any Notes, and click Create.

    The timely-filing days are what the claim scrubber and the timely-filing alerts use for this payer when the tenant has no program-level window: the longest window among the payer's capabilities for the claim's claim type. A second capability with the same claim type and method is refused. Edit and Deactivate on a row change or retire one; there is no delete.

  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 procedure-code rates for the program (a payer exception when only this payer pays differently) via the Procedure Codes tab on the rule-set page in the platform console (/master-data/program-rules/:programRuleId, backed by /platform/master-data/program-rules/:id/procedure-codes) — or the PA fee-schedule SFTP-drop pipeline for bulk loads. Rates are stored in rcm_master.program_rule_procedure_code (was payer_program_procedure_code, #5995); see Master-data administration runbook for schema detail.

  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​

CheckExpected
rcm_master.payer rowexists, is_active=true
Submission tab on the payer pageone active capability per claim type and method the payer takes, with Timely filing days set where the payer has a window
rcm_master.trading_partner linkexists, is_active=true
Routing simulator for the new payerresolves to the expected partner + guide
Test 270 → 271 round tripsucceeds (where applicable)

Troubleshooting​

SymptomCauseFix
Routing resolver returns no_route_foundNo rule matches the claim shapeInspect simulator candidates; tighten or add a rule.
837 generation fails with "trading partner inactive"trading_partner.is_active=false or its credentials purgedRe-activate; re-rotate credentials via Trading partner credential vault.
Timely-filing alerts use the wrong windowA capability for that claim type carries the wrong Timely filing days (the longest one wins), or the tenant's program setting overrides itFix the number on the payer's Submission tab, or blank it; check the tenant's program config. See Reporting.
Customer's 837P missing payer-specific overridesCompanion guide not linkedSet submission_routing_rule.companion_guide_id.

Cross-references​

Next​

2.2 — Add a state companion guide