Tax & Compliance

This page covers the two healthcare-and-tax surfaces of mvs-pay:

• Tax — per-Org sales-tax calculation via TaxJar, wired into Hyperswitch as a tax_processor connector. There is no MVS application code for tax; it is a pure connector-config concern. Hyperswitch calls TaxJar and stamps order_tax_amount on each payment intent.
• IIAS substantiation — IRS Pub 502 / IIAS (Inventory Information Approval System) auto-substantiation for HSA / FSA card payments. This is MVS code: the 90% rule (packages/mvs-pay-sdk/src/lib/iias.ts), the auto-substantiation hook on payment create (apps/mvs-pay-extensions/src/routes/payments.ts, § M26), the IiasSubstantiation persistence model, the CSV export route (apps/mvs-pay-extensions/src/routes/iias-export.ts), and a receipt-PDF service.

These two are independent. TaxJar computes how much sales tax a payment owes. IIAS decides whether an HSA / FSA card was allowed to pay for the basket. A payment can have both, either, or neither.

TaxJar tax integration

Where the wiring lives

TaxJar is not an mvs-pay-extensions route, a SDK namespace, or a UI page. It is a Hyperswitch connector of connector_type: "tax_processor" attached per-business-profile. This is the native-Hyperswitch bias in its purest form: we provision the connector and let Hyperswitch own the tax-calc traffic. The full operator procedure is the TaxJar runbook (M28); this section is the conceptual map.

The contract is: once a business profile has a tax_processor_id, every intent created against that profile — including wallet / express-checkout flows that re-quote tax at sheet-render time — gets order_tax_amount populated by TaxJar. No app-side code path is involved.

The connector model

A profile without a tax_processor_id returns order_tax_amount: 0. That is the intended escape hatch for tax-exempt sub-business-units (e.g. clinical research) — it is not an error state.

Product tax codes (PTCs)

TaxJar uses PTCs to override the default rate per line item — e.g. prescription drugs are exempt in most US states. The catalog table BillableItem carries an optional tax_code column; when present it is forwarded to Hyperswitch as order_details[].product_tax_code.

Full catalog: https://developers.taxjar.com/api/reference/#categories.

What MVS does not do with tax

There is also a salesTax column on transfer_extension (packages/mvs-pay/prisma/schema.prisma), but it is part of the L2/L3 commercial-card data block (alongside shippingAmount, discountAmount, customsDutyAmount), not the TaxJar-computed figure. TaxJar’s result lives on the Hyperswitch intent as order_tax_amount; do not confuse the two.

IIAS substantiation

What IIAS is

IRS Pub 502 plus the IIAS (Inventory Information Approval System) framework let an HSA / FSA card auto-substantiate a payment when at least 90% of the dollar amount is for qualified medical categories. Below that threshold the merchant must provide additional substantiation (copay match, prescription pattern, or manual receipt review).

The single source of truth for the math is packages/mvs-pay-sdk/src/lib/iias.ts. It is deliberately framework-free so the same function runs in mvs-pay-extensions (on payment create), in the mvs-pay UI / receipts, and in e2e specs. It is exported from the SDK root (@mvs/mvs-pay-sdk) as evaluateNinetyPercentRule with types IiasLineItem, IiasLineItemCategory, NinetyPercentRuleInput, NinetyPercentRuleResult. See The SDK.

The 90% rule

1
import { evaluateNinetyPercentRule } from "@mvs/mvs-pay-sdk";
2
3
const { iiasEligibleAmount, passed } = evaluateNinetyPercentRule({
4
  totalAmount, // cents
5
  lineItems: [
6
    { category: "clinic", amount: 9000 },
7
    // ...
8
  ],
9
});

The four tracked categories are clinic, dental, prescription, vision — mapping 1:1 to the healthcare_<category>_amount columns on transfer_extension. The rule semantics, straight from the implementation:

Auto-substantiation on payment create

When POST /v1/payments carries any of healthcare_clinic_amount, healthcare_dental_amount, healthcare_prescription_amount, or healthcare_vision_amount, the payments route (apps/mvs-pay-extensions/src/routes/payments.ts, § M26) builds the line-item array, runs evaluateNinetyPercentRule, and persists one IiasSubstantiation row.

A subtlety in the route: totalAmount is read from the resolved Hyperswitch payment (payment.amount), falling back to the request body amount, and 0 if neither is a number. A totalAmount of 0 would force passed: false by the rule’s own contract.

The IiasSubstantiation model

Defined in packages/mvs-pay/prisma/schema.prisma (@@map("iias_substantiation")), one row per transferExtension (a @unique 1:1 relation). Cascade-deletes with both its organization and its transfer extension.

Verify a payment substantiated:

1
SELECT "totalAmount", "iiasEligibleAmount",
2
       "ninetyPercentRulePassed", "substantiationMethod"
3
  FROM "iias_substantiation"
4
 WHERE "transferExtensionId" = '<transfer_extension_id>';

The IIAS export route

GET /v1/iias-export?from=YYYY-MM-DD&to=YYYY-MM-DD returns a CSV of every substantiation row in the tenant’s date window. Plan administrators upload it to their HSA / FSA payer as proof. Implementation: apps/mvs-pay-extensions/src/routes/iias-export.ts (Phase 5 / M26.5).

CSV schema — one header row, then one row per substantiation:

date,transferId,totalAmount,iiasEligible,passed,method
2026-01-14,pay_abc123,10000,9500,true,iias
2026-02-03,pay_def456,8000,6000,false,manual

passed is the literal string true / false; method is the substantiationMethod. Both transferId and method are RFC-4180 quoted by the route’s csvField helper if they contain a comma, quote, CR, or LF. The response sets content-disposition: attachment; filename="iias-export-<from>-to-<to>.csv".

$
curl -sS \
>
  -H "x-internal-secret: $S" -H "x-mvs-org-id: $O" \
>
  "$EXT_URL/v1/iias-export?from=2026-01-01&to=2026-03-31" \
>
  -o iias-export.csv

Error responses (all 400 unless noted):

Full request/response shape is in the API Reference under the iias-export resource.

Per-payment receipt PDF

apps/mvs-pay-extensions/src/services/receipt-pdf.ts exposes generateIiasReceiptPdf(input) (async), which renders an IRS-Pub-502-compliant HSA / FSA receipt into a Node Buffer using pdfkit (its only runtime dep — @react-pdf/renderer was deliberately avoided). The receipt includes patient name, provider name, date of service, itemized eligible expenses by category, total, and the explicit Pub-502 disclaimer (“Issued for IIAS substantiation per IRS Pub 502”). Inputs are typed via IiasReceiptInput / IiasReceiptLineItem. The buffer can be streamed from a Hono response, emailed, or uploaded to object storage.

The operator-facing receipt payload is assembled by the mvs-pay app at GET /api/transactions/[id]/receipt (apps/mvs-pay/app/api/transactions/[id]/receipt/route.ts), which combines the Hyperswitch payment with the local transferExtension line items / healthcare amounts and renders the UI receipt.

Verification

Troubleshooting

For incident escalation — including any cleartext-PHI exposure from the export or receipt path — follow the Incident Response runbook.

Related pages