User Guide: End-to-End Payment Lifecycle

Last updated: January 15, 2026

---

Overview

This guide covers the complete payment process for building permits, from fee calculation through payment verification. Understanding this lifecycle helps applicants navigate payments successfully and helps staff troubleshoot issues.

---

Payment Lifecycle Overview

---

Step 1: Fee Definition & Calculation

How Fees Are Calculated

The system calculates fees based on:

Fee Types

Application Fees:

• Base permit application fee
• Plan review fees
• Technology fees

Inspection Fees:

• Per-inspection charges
• Reinspection fees (if applicable)
• After-hours inspection surcharges

Other Fees:

• Impact fees
• Infrastructure fees
• Special district fees

---

Step 2: Viewing Your Fee Breakdown

In the Citizen Portal

1. Log in and open your permit application
2. Navigate to the Payments tab
3. View the fee breakdown:

Understanding Fee Items

Each fee line shows:

• Fee name/description
• Unit cost and quantity (if applicable)
• Line total
• Any applied discounts

---

Step 3: Selecting Payment Method

Available Payment Methods

Online Payment Process

1. Click "Pay Now" button
2. Select your payment method
3. System redirects to secure payment provider

---

Step 4: Payment Submission

For Credit/Debit Card (via Govolution)

When you click "Pay Now":

1. Secure Redirect - You're sent to the Govolution payment portal
2. Card Entry - Enter card details on the secure page
3. Verification - Card is verified with your bank
4. Authorization - Payment is authorized
5. Return - You're redirected back to the portal

Information Required:

• Card number
• Expiration date
• CVV/security code
• Billing address
• Email for receipt

For Other Providers (Stripe, PayPal)

1. Click "Pay Now"
2. Select provider (if multiple available)
3. Complete payment on provider's site
4. Return to permit portal

---

Step 5: Payment Processing

What Happens Behind the Scenes

Processing Times

---

Step 6: Payment Confirmation

Successful Payment

Upon successful payment, you'll see:

A receipt has been sent to your email.

Available Actions: Copy Confirmation, Print, Continue

Available Actions:

• Copy Confirmation - Copy number to clipboard
• Print - Print payment receipt
• Continue - Proceed to next steps (e.g., schedule inspection)

Failed Payment

If payment fails:

Please try again or use a different payment method.

Available Actions: Try Again, Use Different Method

Common Failure Reasons:

• Insufficient funds
• Card expired
• Incorrect card details
• Bank security block
• Network timeout

---

Step 7: Verifying Payment Status

In Your Permit Record

After payment, your permit record shows:

Payments Tab:

• Payment status: "Completed"
• Amount paid
• Confirmation number
• Transaction date

Permit Status:

• May change to "Paid" or advance to next workflow step

Email Confirmation

You'll receive an email with:

• Payment receipt
• Confirmation number
• Amount paid
• Permit reference number
• Next steps

---

Step 8: Post-Payment Workflow

What Happens After Payment

Depending on your permit type:

1. Record May Lock - Prevents further applicant edits
2. Staff Notified - Permit moves to review queue
3. Inspections Enabled - You can now schedule inspections
4. Workflow Advances - Permit status updates automatically

Scheduling Inspections

If your permit requires inspections:

1. Return to your permit record
2. Navigate to Inspections tab
3. Click "Schedule Inspection"
4. Select inspection type and preferred date/time

---

Troubleshooting Payment Issues

For Citizens

Q: My payment failed. What do I do? A:

1. Note the error message
2. Verify your card details are correct
3. Check with your bank for any blocks
4. Try a different payment method
5. Contact county staff if problems persist

Q: I was charged but the system shows unpaid. A:

1. Wait 15-30 minutes (processing delay possible)
2. Check your email for confirmation
3. Look for transaction on your bank statement
4. Contact county staff with transaction details

Q: How do I get a receipt? A:

1. Check your email for the original receipt
2. Log in and go to Payments tab
3. Click on the payment entry
4. Use "Print" option

Q: I paid the wrong amount / duplicate payment. A:

1. Do not attempt additional payments
2. Contact county staff immediately
3. Provide confirmation numbers for all payments
4. Staff will process adjustment or refund

For Staff

Q: Applicant claims payment but system shows unpaid. A:

1. Ask for confirmation number
2. Check payment provider admin portal
3. Look for failed/pending payments
4. Verify correct permit record
5. May need to contact provider support

Q: Payment provider error code received. A: Common error codes:

• missing_parameters - Required data not sent
• provider_not_configured - Payment setup incomplete
• invalid_amount - Fee calculation issue
• session_expired - Customer took too long

---

Payment Error Handling

System Error Messages

---

Security & Compliance

Payment Security

• All payments processed through PCI-compliant providers
• Card details never stored in county systems
• Encrypted connections (HTTPS) for all transactions
• Multi-factor authentication on payment portals

Receipt Records

• All payments recorded in permit audit trail
• Receipts available for 7+ years
• Transaction records reconciled daily

---

Related Features

• Payment Management (Admin) - Staff payment tools
• Fee Definitions & Payment Methods - Fee configuration
• Citizen Portal Permit Lifecycle - Full application process
• Inspection Scheduling - Post-payment scheduling

---

Technical Notes

Payment Providers Supported:

• Govolution/Velocity - Auto-submit form with hidden fields
• Stripe - Session-based redirect
• PayPal - OAuth redirect flow

Payment Field Component:

• Location: /apps/entity-manager-app/src/components/PaymentField/FormPaymentField.tsx
• Manages payment sessions and provider redirects
• Handles success/cancel URL callbacks

Fee Calculation:

• Multiple fee types and calculation methods supported
• Dynamic calculation based on form field values
• Tiered fee schedules for permit value ranges

Error Handling:

• Provider configuration validation
• Missing parameter detection
• Graceful failure with user-friendly messages

---

For additional assistance, contact your System Administrator.