Configuration Guide: Fee Definitions & Payment Form Fields

---

Overview

This guide provides comprehensive instructions for configuring Fee Definitions and integrating them with Payment Form Fields. Fee Definitions allow administrators to create reusable fee structures with multiple calculation methods, including tiered pricing based on form inputs like acreage, square footage, or other quantities.

Key Capabilities

• Multiple Calculation Methods: Fixed amount, per-unit, percentage, and tiered calculations
• Dynamic Fee Calculation: Fees calculated based on applicant-provided form inputs
• Tiered Pricing: Complex fee structures with multiple tiers based on ranges (e.g., acreage brackets)
• Additional Charges: Filing fees and technology fees can be added to any fee structure
• Tax and Discount Support: Apply percentage-based tax or discount calculations
• Reusable Definitions: Create once, use across multiple forms

Use Cases

---

Prerequisites

Before configuring fee definitions, ensure you have:

• Admin access to Entity Manager
• Admin access to Form Builder
• A configured Payment Provider (Govolution, Stripe, or PayPal)
• Understanding of your organization's fee schedule

---

Part 1: Creating Fee Definitions

Fee Definitions are created in the Fee Definitions section of Entity Manager and can be used across multiple forms.

Step 1: Navigate to Fee Definitions

1. Open Entity Manager
2. Select your application (e.g., "Building Permits")
3. Click Fee Definitions in the navigation menu
4. Click Add Fee Definition button

---

Step 2: Configure Basic Information

All fee definitions require these basic settings:

Example Configuration:

---

Step 3: Select Calculation Method

Choose the appropriate calculation method based on how the fee should be determined:

Option A: Fixed Amount

Use for flat fees that don't vary based on application details.

When to Use:

• Application filing fees
• Flat inspection fees
• Administrative fees

Example: $150 application fee → Calculation Method: Fixed Amount, Rate: $150.00

---

Option B: Per Unit

Use when fees are calculated based on a quantity multiplied by a rate.

When to Use:

• Square footage fees
• Per-unit licensing fees
• Quantity-based permits

Example: $0.10 per square foot with $50 minimum

Calculation Formula: Total = (Quantity × Unit Value) + Rate

---

Option C: Percentage

Use when fees are calculated as a percentage of another value.

When to Use:

• Technology surcharges
• Administrative percentage fees
• Plan review fees based on construction cost

Example: 2.5% technology fee → Calculation Method: Percentage, Unit Name: application_total, Unit Value: 2.5

---

Option D: Tiered (Dynamic Calculation)

Use for complex fee structures where the rate changes based on ranges. This is the most powerful option for dynamic fee calculation based on form inputs.

When to Use:

• Acreage-based grading fees
• Graduated fee schedules
• Volume-based pricing

---

Step 4: Configure Tiers (For Tiered Calculation)

If you selected "Tiered" as the calculation method, you'll configure individual tiers.

4.1 Understanding Tier Structure

Each tier defines a range and the rate applied within that range:

4.2 Add Tiers

1. Click Add Tier button in the Tiers section
2. Configure the tier settings
3. Click Add Tier Below to add additional tiers
4. Tiers are automatically numbered (Tier 1, Tier 2, etc.)
5. Click on tier name to customize (e.g., "Small Projects", "Large Projects")

4.3 Example: Acreage-Based Grading Fee

This example shows a tiered fee structure for grading permits based on acreage:

How This Calculates:

4.4 Tier Configuration Tips

1. Ensure Continuous Ranges: Tier 1 max should equal Tier 2 min
2. Last Tier: Leave Maximum Value empty for unbounded upper ranges
3. Partial Blocks: Enable when fractional values should be charged (e.g., 2.5 acres)
4. Block Size: Use for grouping (e.g., charge per 1,000 sq ft blocks)

---

Step 5: Save Fee Definition

1. Review all settings
2. Click Create Fee Definition (or Update Fee Definition if editing)
3. The fee definition is now available for use in forms

---

Part 2: Using Fee Definitions in Payment Form Fields

Once fee definitions are created, they can be added to forms via the Payment field type.

Step 1: Add Payment Field to Form

1. Open Form Builder for your target form
2. Drag a Payment field onto the form canvas
3. Click the field to open the configuration sidebar

---

Step 2: Configure Payment Field Basic Settings

---

Step 3: Select Amount Type

Option A: Static Amount

Use when the fee is a fixed amount not dependent on form inputs.

---

Option B: Dynamic Amount

Use when the fee amount comes from another form field.

---

Option C: Calculation (Fee Definitions)

Use when fees should be calculated based on fee definitions and form inputs.

---

Step 4: Add Fee Definition to Payment Field

When Amount Type is "Calculation":

1. Click Add Fee Definition button
2. A modal dialog appears with configuration options

4.1 Configure Fee Definition Modal

Example Configuration:

For a grading permit where acreage determines the fee:

Fee Definition: Grading Permit Fee
Quantity: [Select "Total Acreage" field from form]
Apply Tax: No
Apply Discount: No

1. Click Create to add the fee definition

4.2 View Configured Fee Definitions

After adding, you'll see:

• Fee definition name with quantity field badge
• Tax and Discount settings displayed
• Edit (gear icon) and Delete (trash icon) buttons

---

Step 5: Configure Additional Charges (Optional)

Below the fee definitions, you can add supplemental charges:

Filing Fee

1. Check Filing Fee Required checkbox
2. Enter the filing fee amount (e.g., $25.00)

Technology Fee

1. Check Technology Fee Required checkbox
2. Enter the technology fee percentage (e.g., 2.5%)

---

Step 6: Review Total Fee Formula

The system displays a formula showing how the total is calculated:

Total Fee Amount = [Fee Definition(s)] + Filing Fee + (Total × Technology Fee %)

---

Step 7: Configure Validation (Optional)

---

Step 8: Save Form

1. Click Save to save form configuration
2. Click Publish to make the form available

---

Part 3: Applicant Experience

What Applicants See

When applicants fill out the form:

1. Enter Quantity: Applicant fills in the quantity field (e.g., enters "3.5" in Total Acreage field)

2. View Fee Breakdown: The Payment field displays a breakdown:

Applicant clicks "Pay Now" to proceed to payment provider

1. Complete Payment: Click "Pay Now" to proceed to payment provider

---

Part 4: Advanced Configuration Examples

Example 1: Construction Permit with Square Footage Tiers

Fee Definition: Building Permit Fee

Form Configuration:

• Quantity Field: "Total Square Footage" (number input on form)
• Filing Fee: $50
• Technology Fee: 2%

---

Example 2: Business License with Annual Revenue Tiers

Fee Definition: Annual Business License Fee

Form Configuration:

• Quantity Field: "Gross Annual Revenue" (number input on form)
• Filing Fee: $25

---

Example 3: Multiple Fee Definitions in Single Payment

For permits requiring multiple fees:

1. Add first fee definition (e.g., "Plan Review Fee")

   • Quantity: Square Footage field

2. Add second fee definition (e.g., "Inspection Fee")

   • Quantity: Number of Stories field

3. Add third fee definition (e.g., "Fire Safety Review")

   • Quantity: Building Type field (if numeric) or static

The total combines all fee definitions plus any filing/technology fees.

---

Troubleshooting

Fee Definition Not Appearing in Dropdown

Check:

1. Fee Definition status is set to "Active"
2. Effective date is current or past
3. You're searching in the correct application

Calculation Returning Wrong Amount

Check:

1. Tier ranges are continuous (no gaps)
2. Minimum/Maximum values are correct
3. Rate and Rate Per Unit are set correctly
4. Quantity field is providing the expected value

Payment Amount Shows $0

Check:

1. Quantity field has a value entered
2. Fee definition is properly linked
3. Tier covers the input value range

"No providers configured" Message

Check:

1. Navigate to Administration → Payments (via profile icon)
2. Configure at least one payment provider
3. Payment provider must be active

---

Technical Reference

Fee Definition Data Structure

{
  name: string;              // "Grading Permit Fee"
  fee_code: string;          // "FEE-GRAD-001"
  status: 'active' | 'inactive';
  effective_date: Date;
  calc_method: 'fixed_amount' | 'per_unit' | 'percentage' | 'tiered';
  base_rate?: number;        // For fixed_amount, per_unit
  unit?: string;             // For per_unit, percentage
  unit_value?: number;       // For per_unit, percentage
  tiers?: [{                 // For tiered
    name: string;
    min: number;
    max?: number;
    rate?: number;
    rate_per_unit?: number;
    unit_block_size?: number;
    partial_allowed?: boolean;
  }];
}

Fee Schedule Item (Form Configuration)

{
  fee_id: string;            // Reference to FeeDefinition._id
  fee_name: string;          // Display name
  permit_field_id: string;   // Form field for quantity
  tax?: string;              // Form field for tax
  discount?: string;         // Form field for discount
}

Amount Type Options

Category Options (Fee Definitions)

---

Related Documentation

• Request Additional Fee Workflow - Staff-initiated fee requests
• Form Builder - Form configuration

---

For additional configuration assistance, contact the GovAssist support team.