How Customer Payments Are Processed

Source: customer_payment.rb:139-204, customer_payments_controller.rb:20-235

• Payment amount is auto-calculated from the sum of payment items -- any user-supplied amount is overridden
• Cannot save a payment with a single empty payment line (no invoice, amount = 0)
• Payment items total must match payment methods total (compared at 2 decimal places) or processing fails
• Cannot overpay an invoice -- each payment item amount is checked against the invoice's balance_due
• No duplicate invoice references allowed in a single payment -- error: "an invoice is referenced twice"
• Processing creates CustomerPaymentDispersal records linking methods to items using FIFO allocation (oldest payment item first by created_on)
• Handles partial allocations when a single payment method spans multiple items
• Each invoice's balance_due is reduced; if it drops to zero or below, the invoice auto-closes
• Customer account is credited; branch customer is also credited if a branch_link exists
• Payment status is set to closed after successful processing
• If a dispersal record fails to save, an EventLog is created, a support email is sent to Workshop Software, and the entire transaction rolls back
• Assembly Payments processing saves the receipt number from the terminal response before processing begins

Support scenarios

• "Payment methods amount doesn't match items" -> the total of all payment methods (cash, EFTPOS, etc.) must exactly equal the total of all invoice allocations at 2 decimal places
• "Can't apply more than the invoice balance" -> payment items cannot exceed the invoice's current balance_due
• "The invoice says it's referenced twice" -> the same invoice appears on two payment lines; combine them into one line
• "Payment processed but something went wrong internally" -> check if Workshop Software support received an automated email about a failed dispersal save