User Guide: Payment Management (Admin)

Last updated: January 15, 2026

---

Overview

The Payment Management feature allows administrators and authorized staff to view, manage, and track payment entries for permits. This includes viewing payment status, processing history, and managing payment-related workflows.

Key Capabilities

• View and manage payment entries for permits
• Track payment status and history
• Access audit logs for payment changes
• Configure payment fields and fee structures
• Handle payment adjustments and corrections

---

Understanding Payment Status

Payment Status Values

Payment Lifecycle

---

Viewing Payment Information

Accessing Payment Records

1. Open the permit record
2. Navigate to the Payments tab
3. View payment summary and history

Payment Summary View

The payment summary shows:

Payment History List

View all payment attempts and transactions:

---

Payment Details View

Accessing Full Details

1. In the Payments tab, click on a payment entry
2. A details panel opens on the right side
3. View comprehensive payment information

Detail Sections

Amount Section:

• Total amount charged
• Fee breakdown by category
• Applied discounts (if any)

Payment Method Section:

• Payment type (Credit Card, ACH, etc.)
• Card details (last 4 digits, expiration)
• Billing address

Transaction Information:

• Transaction ID from payment provider
• Processing timestamp
• Authorization code
• Provider response details

---

Managing Payment Entries

Viewing Payment Audit Log

All payment changes are tracked:

1. Open payment details
2. Scroll to Activity Log or History section
3. View timeline of all payment events

Logged Events:

• Payment initiated
• Payment status changes
• Adjustment applied
• Notes added
• Manual overrides

Adding Notes to Payments

Staff can add notes for documentation:

1. Open payment details
2. Click Add Note or Add Comment
3. Enter your note (e.g., "Customer called about delay")
4. Save the note

Notes appear in the activity log with timestamp and author.

---

Payment Configuration

For Administrators

Payment fields in permit applications are configured in Entity Manager.

Fee Structure Configuration

Navigate to: Entity Manager → [Entity Type] → Fields → Payment Field

Configuration Options:

• Fee types (flat, calculated, tiered)
• Fee categories (application, inspection, plan review)
• Payment providers enabled
• Required vs. optional payment
• Auto-calculation rules

Payment Provider Settings

Navigate to: Administration → Payment Providers

Supported Providers:

• Govolution/Velocity - Primary government payment processor
• Stripe - Card processing
• PayPal - Alternative payment method

Provider Configuration:

• API credentials (encrypted)
• Environment (Production/Sandbox)
• Callback URLs
• Test mode settings

---

Handling Payment Issues

Failed Payment Investigation

When a payment fails:

1. Open the payment record
2. Check the Error Message field
3. Common failure reasons:
   • Insufficient funds
   • Card declined
   • Invalid card details
   • Network timeout
   • Provider system error

Retrying Failed Payments

For Citizens:

1. Review the error message
2. Update payment method if needed
3. Click "Pay Now" to retry

For Staff (if assisting):

1. Verify permit details are correct
2. Confirm fee calculation
3. Guide citizen through retry process
4. Document any issues in notes

Payment Adjustments

Note: Manual payment adjustments require elevated permissions.

When adjustments may be needed:

• Fee calculation error
• Approved discount or waiver
• Duplicate payment
• Partial refund

Process:

1. Document reason for adjustment
2. Obtain supervisor approval
3. Apply adjustment in system
4. Update payment record
5. Notify applicant if applicable

---

Payment Reports

Available Reports

Staff with appropriate access can generate:

Accessing Reports

1. Navigate to Reports section
2. Select Payment Reports
3. Choose report type and date range
4. Export as needed (PDF, Excel)

---

Permissions Required

Role-Based Access

Sensitive Data Protection

Payment details (full card numbers, CVV) are:

• Never stored in the system
• Handled by payment provider
• Only last 4 digits visible
• PCI DSS compliant

---

Troubleshooting

Common Staff Issues

Q: I can't see the Payments tab on a permit. A: Check:

1. Entity type has payment field configured
2. You have permission to view payment data
3. Payment has been initiated (tab may be hidden until needed)

Q: Payment shows completed but permit status didn't update. A: This may indicate:

1. Automation not configured for this permit type
2. Manual status update required
3. Contact system administrator

Q: How do I process a refund? A: Refunds are processed through the payment provider's system, then documented in the permit record. Contact your supervisor for the refund process.

Q: Applicant claims they paid but I don't see it. A:

1. Verify the correct permit record
2. Check payment date range
3. Look for failed payment attempts
4. Verify with payment provider if needed
5. Check if payment went to different permit

---

Integration Points

Automations Triggered by Payment

Payment completion can trigger:

• Permit status update to "Paid"
• Notification emails to staff
• Record lock (prevent further edits)
• Next workflow step initiation

Inspection Scheduling

After payment:

• Inspection scheduling may be enabled
• Payment confirmation required for certain inspection types
• See: End-to-End Payment Lifecycle

---

Related Features

• End-to-End Payment Lifecycle - Complete payment process
• Fee Definitions & Payment Methods - Configuring fees
• Audit Logs & History - Tracking changes
• Permit Record Locking - Post-payment locking

---

Technical Notes

Component Locations:

• Payments Tab: /apps/citizen-portal-host/src/pages/AddApplicationForm/tabRoutesComponents/payments/
• Payment Field: /apps/entity-manager-app/src/components/PaymentField/
• Payment Status Modal: /apps/citizen-portal-host/src/components/PaymentStatusModal/

Payment Field Component:

• FormPaymentField.tsx - Renders payment UI with provider handling
• Supports: Govolution (form submit), Stripe/PayPal (redirect)
• Manages isPaid status

API Behavior:

• Payment sessions created with application_id, message_version, remittance_id
• Webhooks update payment status
• Fee calculations from fee_definition service

---

For additional assistance, contact your System Administrator.