⚠️ Important: This article is for organization administrators. For the commuter-facing guide, see Payments & Earnings.
Every financial event in CommuteHub - a parking session, a permit charge, a commute bonus payout, or a refund - is tracked as a Transaction Entry. These entries are created automatically and flow through a defined set of states as they move from creation to payroll processing.
The management dashboard provides full visibility into these entries via the Payments and Earnings Insights report where you can filter by state, category, user, date range, and more.
State Flow Diagram
The diagram below shows how a transaction entry moves through its lifecycle. Entries start at the top and flow toward their final state at the bottom.
Entry States
| State | Description | Commuter Sees | Admin Action |
|---|---|---|---|
| Pending Creation | Entry created (parking session, permit, commute bonus). Waiting for next payroll export. | Gray row | No action needed. Will be picked up by the scheduled export. |
| Pending Cancellation | A cancellation entry waiting to be uploaded (e.g. approved appeal created before export). | Gray row | No action needed. Next export run picks it up. |
| Pending Acknowledgement | Exported to payroll via SFTP. Waiting for the vendor's return file to confirm. | Gray row | Exported but not yet confirmed. Acknowledgement task must run. |
| Processed ✅ | Final success state. Confirmed by payroll vendor (or directly processed for customers without acknowledgement). | Red (charge) or Green (credit) | Complete. No further action needed. |
| Acknowledgement Failed ⚠️ | Exported but the return file didn't match — entry was missing or the amount differed. | Red (charge) or Green (credit) with an error message | Requires investigation. Check metadata for failure reason and amount diff. |
| Cancelled | Voided before export. No payroll impact. | "Cancelled" indicator | Historical record. Entry was never sent to payroll. |
Entry Types
| Type | Description | Example |
|---|---|---|
| Deduction | Regular payroll deduction for a charge (parking session, permit, etc.) | Daily parking charge of $8.00 |
| Cancellation | Stops a previous deduction by creating a matching entry with an end date | Cancel a $50/month permit deduction |
| Reimbursement | One-time credit back to the employee (refund from approved appeal, commute bonus) | Refund of $6.50 from approved appeal |
| Note | Informational entry with no financial impact. Audit trail only. | Admin note explaining a manual adjustment |
Entry Categories
| Category | Description |
|---|---|
| Parking Charge | Daily parking sessions, permits, reserved spots |
| Credit | Refunds from approved appeals, admin adjustments |
| Commute Bonus Payout | Earnings from sustainable commute trips |
| Commute Bonus Donation | Portion of commute bonus donated to charity |
| Custom | Organization-specific entry categories |
Destinations
Each entry has a destination that determines how the financial impact is applied:
| Destination | Description |
|---|---|
| Payroll | Exported to the payroll vendor via SFTP. Appears on the employee's paycheck. |
| Balance | Applied to the user's parking balance. Used for refunds from approved appeals. |
| Accounts Payable | Routed to accounts payable (e.g. commute bonus payouts via check or direct deposit). |
The Export & Acknowledgement Pipeline
Step 1: Payroll Export
A scheduled task runs at the end of each payroll period. It collects all entries in Pending Creation and Pending Cancellation states, generates a payroll file (CSV/TSV), and uploads it to the customer's SFTP server.
After a successful upload, entries transition to either:
- Processed — if the customer has no acknowledgement flow, or
- Pending Acknowledgement — if the customer's payroll system sends back a return file.
Step 2: Acknowledgement (when configured)
For customers with acknowledgement enabled, the payroll vendor processes the file and drops a return file back on the SFTP server. A separate scheduled task reads this return file and matches each row by batch ID and amount.
Step 3: Handling Failures
When an entry lands in Acknowledgement Failed, there is a discrepancy between what CommuteHub exported and what the payroll system reported. Common reasons:
| Failure Reason | What It Means | Action Required |
|---|---|---|
| Not present in return file | The payroll system didn't include this entry in their response. | Contact the payroll vendor to verify the entry was received. |
| Amount mismatch | The return file amount differs from the exported amount. | Check the entry's metadata for the expected vs. actual amounts. Investigate whether the payroll system adjusted the charge. |
Cancellation & Refund Flow
When an appeal is approved or a charge is cancelled, the system determines the correct action based on whether the entry has already been exported to payroll:
If NOT yet exported (Pending Creation): The entry is simply set to Cancelled. It never reaches payroll, so no refund is needed. The commuter's Payments & Earnings page stops showing the pending charge.
If already exported (Processed / Pending Acknowledgement / Acknowledgement Failed): The charge has already been deducted from the employee's paycheck. The system credits the refund amount to the user's parking balance and creates a Reimbursement entry. The balance is automatically applied against future parking charges.
Key Behaviors
| Entries are never deleted | Transaction entries are immutable once created. Cancellations create new entries rather than deleting old ones. This preserves the full audit trail. |
| Multiple entries per request | A single parking purchase or permit approval may generate multiple entries (e.g. pre-tax and post-tax deductions with different deduction codes). Each entry flows through the state machine independently. |
| Balance applied first | When a user has parking balance (from refunds), it's automatically applied to future charges before anything is sent to payroll. This reduces the payroll deduction amount. |
| Commute bonus offsets | Commute bonus earnings are applied against parking charges within the same payroll period. The net amount is what appears on the employee's paycheck. |