Overweights Chargeback
Apply chargeback (individual or bulk) from the Overweights screen when a provisional refund must be reversed—e.g. when the carrier confirms the refund was correct and the amount must be deducted from the client's balance.
Overview
When an admin needs to reverse an already-accepted overweight refund, the system supports chargeback: debiting the client balance, setting the ticket to Rejected, updating the compensation and carrier payment status, and creating an audit record. Chargeback is available only for tickets that are Solved and have an approved refund (compensation in ACCEPTED status). The same Overweights table supports both the accept/reject flow (for pending tickets) and the chargeback flow (when the filter is Solved); the bulk action label and row actions change accordingly.
Key Concepts
| Concept | Description |
|---|---|
| Chargeback | Reversal of a provisional refund: debit client balance, set ticket to Rejected, update compensation to CHARGEBACK and carrier payment to Not compensated. |
| Solved (ACCEPTED) | Ticket status meaning the refund was approved; only these tickets are eligible for chargeback. |
| Eligibility | Ticket status = Solved and compensation exists with status ACCEPTED. Only eligible rows are selectable for chargeback when the filter is Solved. |
Data Flow
Chargeback path (bulk or single)
Database
Tables
| Table | Purpose |
|---|---|
compensations | On chargeback: status → CHARGEBACK, chargeback_by, chargeback_transaction_amount, utc_chargeback_at, chargeback_surcharge_id, carrier_payment_status → UNPAID. No new columns. |
company_tickets | ticket_status_id → DECLINED (Rejected) when chargeback is applied. |
company_ticket_comments / company_ticket_history | One comment and one history row with the chargeback reason. |
surcharges | New row (NEGATIVE type, chargeback category) created by createChargeBack for balance reversal. |
compensations_history / adjustments | One audit record per chargeback for traceability. |
Key Relationships
Compensations link to company_tickets (ticket_id) and surcharges. Chargeback updates the same compensation row and creates a new surcharge row for the debit. Ticket comment and history reference the same ticket.
Key Decisions
| Decision | Reasoning | Alternatives Considered |
|---|---|---|
| Reuse refunds.util.chargeback | Single place for balance debit, surcharge, compensation update, ticket status; avoids duplication and keeps behavior consistent with refunds chargeback. | Implementing separate chargeback logic only for overweights. |
| Chargeback only when Solved + ACCEPTED | Only tickets that already have an approved refund can be reversed; eligibility is clear and backend-validated. | Allowing chargeback on other statuses. |
| Conditional bulk action by filter | When the user filters by Solved, they are working with "refunds to reverse"; showing "Apply bulk chargeback" instead of accept/reject avoids confusion. | Always showing both accept/reject and chargeback. |
| Same endpoint for single and bulk | One payload with compensation_ids array; frontend sends one id for individual chargeback. | Separate endpoints for single vs bulk. |
Dependencies
- Internal: refunds.util (chargeback, createChargeBack), companies.util (insertTicketComment, insertTicketHistory), Overweights table (filters, bulk buttons, row actions).
- External: None; uses existing balance and surcharge infrastructure.
Related Documentation
- User Guide — Step-by-step instructions for applying chargeback (individual or bulk).
- API — Endpoint reference for
POST /overweights/chargeback. - UI — Overweights screen, Solved filter, chargeback modal, and selection rules.