{"slug": "a-processor-neutral-json-schema-for-auditing-payment-processing-statements", "title": "A Processor-Neutral JSON Schema for Auditing Payment Processing Statements", "summary": "Lifted Holdings has released an open payment processing statement audit kit with a processor-neutral JSON schema designed to standardize how merchant statements are compared. The schema, published in the Lifted Holdings payment-processing-resources repository, defines a small data model with fields for statement period, card volume, transaction count, total processing fees, effective rate, pricing model, and fee groups, aiming to make the true cost of accepting cards transparent without collecting cardholder data.", "body_md": "Merchant processing statements are built for billing, not comparison. Two statements can describe the same monthly card volume with completely different labels, subtotals, and pricing structures. That makes the most basic question—“what did accepting cards actually cost?”—harder to answer than it should be.\n\nWe wanted a small data model that works for a spreadsheet, a software workflow, or an AI-assisted review without collecting cardholder data. The result is an open **payment processing statement audit kit** with:\n\nThe maintained guide and downloads live at [liftedpayments.com/payment-processing-statement-audit](https://liftedpayments.com/payment-processing-statement-audit/). The versioned files are also public in the [Lifted Holdings payment-processing-resources repository](https://github.com/Lifted-Holdings/payment-processing-resources).\n\nThe first calculation is the effective rate:\n\n```\neffective rate = total processing fees / total card volume\n```\n\nIf a fictional merchant processed `$125,000.00`\n\nand paid `$2,864.75`\n\nin total processing-related fees:\n\n```\n2864.75 / 125000 = 0.022918 = 2.2918%\n```\n\nThe data model stores `0.022918`\n\n, not `2.2918`\n\n. Keeping the value as a decimal avoids ambiguity in APIs and calculations; multiply by 100 only for percentage display.\n\nThe hard part is not division. It is making sure the numerator contains every fee from the same period as the volume denominator. Monthly charges, authorization fees, compliance-program fees, gateway items, equipment charges, and adjustments can all disappear from a comparison if someone copies only the most visible subtotal.\n\nThe required top-level fields are deliberately small:\n\n```\n{\n  \"statement_period\": {\n    \"start\": \"2026-06-01\",\n    \"end\": \"2026-06-30\"\n  },\n  \"card_volume\": 125000.00,\n  \"transaction_count\": 1860,\n  \"total_processing_fees\": 2864.75,\n  \"effective_rate\": 0.022918,\n  \"pricing_model\": \"interchange_plus\",\n  \"fee_groups\": []\n}\n```\n\n`pricing_model`\n\nuses a bounded set:\n\n```\ninterchange_plus\nflat_rate\ntiered\nsubscription\ndual_pricing\nunknown\n```\n\n`unknown`\n\nmatters. A statement parser should not guess a pricing model from one line item. It is better to preserve uncertainty than manufacture a confident but wrong classification.\n\nStatement labels vary. The audit model groups them by economic role:\n\n`interchange`\n\n— card- and transaction-specific wholesale costs;`assessments`\n\n— network assessments and access charges;`processor_markup`\n\n— percentage and per-transaction provider markup;`authorization`\n\n— approval, decline, AVS, gateway, and batch items;`monthly`\n\n— account, statement, minimum, and recurring platform charges;`pci`\n\n— compliance-program or noncompliance fees;`equipment`\n\n— terminal purchase, rental, or lease costs;`chargebacks`\n\n— chargeback and retrieval-related items; and`other`\n\n— adjustments that cannot be classified honestly.That taxonomy does not pretend every fee is avoidable. It makes the statement explainable. Wholesale cost, provider markup, fixed overhead, and operational exceptions stop being one opaque total.\n\nThe repository publishes a Draft 2020-12 schema at:\n\n[schema/payment-statement-audit.schema.json](https://github.com/Lifted-Holdings/payment-processing-resources/blob/main/schema/payment-statement-audit.schema.json)\n\nWith Python and `jsonschema`\n\n, validation is straightforward:\n\n``` python\nimport json\nfrom pathlib import Path\n\nfrom jsonschema import Draft202012Validator\n\nschema = json.loads(\n    Path(\"schema/payment-statement-audit.schema.json\").read_text()\n)\nrecord = json.loads(\n    Path(\"examples/payment-statement-audit-example.json\").read_text()\n)\n\nDraft202012Validator(schema).validate(record)\n\ncalculated = round(\n    record[\"total_processing_fees\"] / record[\"card_volume\"],\n    6,\n)\nassert calculated == record[\"effective_rate\"]\n```\n\nSchema validation proves structure, not business truth. A human or statement-specific parser still has to confirm that the extracted totals match the source document and cover the same dates.\n\nAn audit needs monthly totals. It does **not** need payment credentials or personal identity data.\n\nNever put these into a public repository, issue, prompt, or shared audit file:\n\nThe example in the repository is entirely synthetic. It does not describe a real merchant, and its fee-group amounts exist only to demonstrate the file structure and calculation.\n\nOnce statements are normalized, a useful comparison follows five rules:\n\nFor a quick manual check, the [free effective-rate calculator](https://liftedpayments.com/effective-rate-calculator) performs the same core math in the browser without transmitting the values entered.\n\nPayment pricing becomes easier to discuss when the underlying terms are explicit. A versioned schema also gives developers and agents a stable output contract instead of another unstructured summary.\n\nThe kit is licensed under CC BY 4.0. Reuse it, adapt it, or build a parser around it. The requested attribution is:\n\nLifted Payments payment statement audit model —\n\n[https://liftedpayments.com/payment-processing-statement-audit/]\n\nIf you would rather have a payments team review a real statement and design the processing technology around how the business operates, [start the Lifted Payments merchant application](https://liftedholdings.com/apply).", "url": "https://wpnews.pro/news/a-processor-neutral-json-schema-for-auditing-payment-processing-statements", "canonical_source": "https://dev.to/daniel_wilsonkemp_62b88a/a-processor-neutral-json-schema-for-auditing-payment-processing-statements-2cg2", "published_at": "2026-08-02 16:32:52+00:00", "updated_at": "2026-08-02 17:18:35.283423+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["Lifted Holdings", "Lifted Payments"], "alternates": {"html": "https://wpnews.pro/news/a-processor-neutral-json-schema-for-auditing-payment-processing-statements", "markdown": "https://wpnews.pro/news/a-processor-neutral-json-schema-for-auditing-payment-processing-statements.md", "text": "https://wpnews.pro/news/a-processor-neutral-json-schema-for-auditing-payment-processing-statements.txt", "jsonld": "https://wpnews.pro/news/a-processor-neutral-json-schema-for-auditing-payment-processing-statements.jsonld"}}