US Surcharge Compliance
Surcharge / Cash-Discount Compliance Tracker for US states and card-brand rules
Surcharge / Cash-Discount Compliance Tracker for US states and card-brand rules
Key Features
State Surcharge Rules
Ships pre-seeded with a us.surcharge.state.rule record for all 50 states + DC, each carrying a two-letter USPS code, a surcharge cap (3.0%), and a cash-discount and disclosure flag. Connecticut and Massachusetts are seeded with surcharge_allowed = False to reflect their statutory surcharge bans, while cash discounting stays legal nationwide.
Card Brand Caps
Seeded us.surcharge.card.brand.rule records for Visa (3%, lowered from 4% in April 2023), Mastercard (4%), American Express and Discover (3%), each flagged with requires_registration for the 30-day network notice and surcharge_debit = False to keep debit / prepaid cards out of scope, in line with the Durbin Amendment.
Effective Cap Engine
The effective_cap() helper picks the most restrictive of the state cap and the card-brand cap, always bounded by the absolute 4% network ceiling, and blocks the surcharge outright when the state rule marks it as banned. Every calculation returns a machine-readable reason code plus a human-readable explanation for the transaction log.
Cash-Discount / Dual Pricing
The compute_cash_discount() helper models legal-nationwide dual pricing: post a single credit price and discount it for cash payers, clamped to 0–100% of the price. derive_dual_prices() returns both the posted (credit) price and the true cash price from one compliant surcharge percentage.
Immutable Transaction Log
Every evaluation is recorded on us.surcharge.transaction with a sequence-based reference, applied percentage, cap used, and compliant / capped / blocked flags. Once a record moves to the Applied state its amounts, mode and rule links are frozen — the model's write() raises a UserError on any attempt to edit a locked audit record.
Compliance Enforcement
Applying a transaction runs _check_enforcement(), which blocks surcharging in ban states unless the record is explicitly marked override_ban with a documented justification, and blocks apply until the required disclosure is acknowledged. Both checks can be toggled company-wide from Settings.
Disclosure Acknowledgement Log
On apply, build_disclosure_text() generates the standard point-of-sale surcharge disclosure sentence and stores it on us.surcharge.disclosure.log, linked to the transaction, the customer, the acknowledging user, and a timestamp — giving auditors a paper trail that the customer was told about the surcharge before it was charged.
Settings & Compliance Summary
Company-level defaults (default surcharge %, default pricing mode, enforce-compliance, require-disclosure) live in Settings as ir.config_parameter values. The engine's compliance_summary() aggregates total, compliant, capped and blocked transaction counts into a compliance-rate KPI for management review.
Screenshots
Why Choose This Module
Apply credit-card surcharges or cash-discount (dual) pricing while staying inside each US state's surcharge caps and bans, the Visa/Mastercard/Amex/ Discover card-brand caps, and disclosure requirements. Every evaluation is logged as an immutable audit record.
Specifications
- Compatible: Odoo 18.0 / 19.0
- License: OPL-1
- Languages: English
- Author: Pokutsoft
- Dependencies: base, mail
- Support: support@pokutsoft.com
Update date: 2026-07-05