User Guide: Fee Definitions & Payment Methods

Last updated: January 15, 2026

---

Overview

This guide covers how fees are defined in the system and how applicants can select and complete payments. Administrators configure fee templates and payment providers, while applicants experience the payment selection and processing.

---

For Citizens: Understanding Fees

Fee Types You May Encounter

How Fees Are Calculated

Fees may be calculated using:

Viewing Your Fees

1. Open your permit application
2. Navigate to the Payments tab
3. View the fee breakdown showing:
   • Individual fee items
   • Unit costs and quantities
   • Subtotals and totals
   • Any applied discounts

---

For Citizens: Payment Methods

Available Payment Options

Depending on configuration, you may pay using:

Online Payment Process

1. Navigate to your permit → Payments tab
2. Review the fee breakdown
3. Click "Pay Now"
4. You're redirected to the secure payment provider (Govolution, Stripe, or PayPal)
5. Enter your payment information
6. Complete the transaction
7. Return to the portal with confirmation

Payment Confirmation

After successful payment:

• Confirmation number displayed
• Email receipt sent
• Payment status updates in permit
• Permit workflow may advance

---

For Administrators: Configuring Fee Definitions

Accessing Fee Configuration

1. Navigate to Entity Manager
2. Select the entity/permit type
3. Go to Fee Definitions or Payment Settings

Creating a Fee Definition

Step 1: Basic Information

• Fee Name: "Building Permit Application Fee"
• Fee Code: "BLD-APP-FEE"
• Description: Brief description of the fee
• Category: Application, Inspection, etc.
• Department: DILP, Fire, etc.

Step 2: Calculation Method

Step 3: Conditions (Optional)

• When this fee applies
• Required permit types
• Value thresholds
• Project characteristics

Step 4: Save and Activate

• Review configuration
• Save the fee definition
• Enable for use

Fee Definition Example

Fee Name: Building Permit Fee | Fee Code: BLD-PERMIT-001 | Type: Tiered

Managing Fee Schedules

Viewing All Fees:

1. Go to Administration → Fee Definitions
2. See list of all configured fees
3. Filter by department, category, or status

Editing Fees:

1. Click on a fee definition
2. Modify as needed
3. Save changes
4. Changes apply to new applications (existing unaffected)

Deactivating Fees:

1. Open the fee definition
2. Set status to "Inactive"
3. Fee no longer appears in new applications

---

For Administrators: Payment Provider Configuration

Supported Payment Providers

Configuring Govolution

1. Navigate to Administration → Payment Providers
2. Select Govolution/Velocity
3. Enter configuration:
   • Merchant ID
   • API Key (encrypted)
   • Environment: Production or Sandbox
   • Payment Gateway URL
4. Test the connection
5. Save and activate

Configuring Stripe

1. Navigate to Administration → Payment Providers
2. Select Stripe
3. Enter configuration:
   • API Secret Key (encrypted)
   • Publishable Key
   • Webhook Secret
   • Environment: Live or Test
4. Configure webhooks in Stripe dashboard
5. Test with test cards
6. Save and activate

Configuring PayPal

1. Navigate to Administration → Payment Providers
2. Select PayPal
3. Enter configuration:
   • Client ID
   • Client Secret (encrypted)
   • Environment: Live or Sandbox
4. Test the integration
5. Save and activate

Testing Payment Providers

Before going live:

1. Use sandbox/test mode
2. Process test transactions
3. Verify webhooks work
4. Test success and failure scenarios
5. Check notification flow
6. Validate record updates

---

For Staff: Working with Fees

Viewing Applicant Fees

1. Open permit record
2. Go to Payments tab
3. See calculated fees
4. View payment status

Fee Adjustments

Requires appropriate permissions

When adjustments are needed:

1. Document reason for adjustment
2. Obtain supervisor approval
3. Apply adjustment in system
4. Note appears in audit log
5. Notify applicant if needed

Common Fee Scenarios

Waiver/Exemption:

• Government projects may be exempt
• Non-profit discounts
• Documented fee waivers

Refund:

• Application withdrawn
• Overpayment
• Processing error

Additional Fees:

• Scope changes
• Re-inspection required
• Expedited review requested

---

Payment Field Configuration

Adding Payment Field to Entity

1. Open entity in Entity Manager
2. Navigate to Fields
3. Add Payment Field type
4. Configure:
   • Label (e.g., "Permit Fees")
   • Required (yes/no)
   • Fee definitions to include
   • Display options
5. Save field configuration

Payment Field Options

---

Troubleshooting

For Citizens

Q: My fee seems wrong. What do I do? A: Review the fee breakdown details. If you believe there's an error, contact county staff with specific questions about the calculation.

Q: I can't complete payment - it keeps failing. A:

1. Check card details are correct
2. Verify sufficient funds
3. Try a different payment method
4. Contact your bank if card is being blocked
5. Contact county staff if issues persist

Q: Can I get a refund? A: Contact Permitting Support to discuss refund options based on your situation.

For Administrators

Q: Fee calculations are incorrect. A: Check:

• Fee definition configuration
• Calculation formula/tiers
• Input field mappings
• Test with known values

Q: Payments aren't being recorded. A: Verify:

• Payment provider webhooks configured
• Webhook URL accessible
• Provider credentials valid
• Check provider dashboard for errors

Q: How do I change fees for existing applications? A: Fee definitions apply at time of calculation. For existing applications, manual adjustments may be needed with appropriate approvals.

---

Best Practices

For Administrators

1. Document all fees - Clear descriptions help citizens understand
2. Test thoroughly - Verify calculations before go-live
3. Regular reviews - Update fee schedules as needed
4. Provider monitoring - Check provider status regularly
5. Backup credentials - Securely store provider credentials

For Staff

1. Know the fee schedule - Understand how fees are calculated
2. Explain clearly - Help citizens understand their fees
3. Follow adjustment procedures - Document all changes
4. Escalate issues - Report calculation problems promptly

---

Related Features

• Payment Management - Viewing and managing payments
• End-to-End Payment Lifecycle - Complete payment process
• Audit Logs & History - Payment change tracking

---

Technical Notes

Fee Definition Storage:

• Configured in entity manager service
• Supports multiple calculation types
• Versioned for audit compliance

Payment Field Component:

• Location: /apps/entity-manager-app/src/components/PaymentField/
• Supports multiple providers
• Handles redirect and callback flows

Provider Integration:

• Webhooks for status updates
• Encrypted credential storage
• Environment separation (sandbox/live)

---

For additional assistance, contact your System Administrator.