Overweights Chargeback API

API for applying chargeback from the Overweights screen. The existing PUT /overweights/ticket/:id is unchanged and is not used for chargeback.

POST /overweights/chargeback

Applies chargeback to one or more compensations (provisional refunds). For each compensation: debits the client balance, sets the ticket to Rejected, adds comment and history with the reason, updates the compensation to CHARGEBACK and carrier_payment_status to UNPAID, and creates an audit record.

Authentication

• Strategy: token_admin

Payload

Field	Type	Required	Description
compensation_ids	number[]	Yes	List of compensation ids. Each must exist, belong to a ticket with status Solved (ACCEPTED), and have compensation status ACCEPTED.
review_comment	string	Yes	Reason for the chargeback (stored in ticket comment and history).

Request example

Bulk chargeback:

{
  "compensation_ids": [101, 102, 103],
  "review_comment": "Carrier confirmed refund incorrect; reversing per report."
}

Individual chargeback: send a single-element array, e.g. "compensation_ids": [101].

Validation (backend)

• compensation_ids: required, non-empty array of numbers.
• review_comment: required, non-empty string.
• For each compensation_id:
  • Compensation must exist.
  • Associated ticket must have ticket_status_id === TICKET_STATUS.ACCEPTED (Solved).
  • Compensation must have status === REFUNDS_STATUS.ACCEPTED.
• If any validation fails for an id, return 400 with a clear message (e.g. "Compensation not found or not eligible for chargeback").

Success response

• Status: 200
• Body: { "data": true } (or, if implementation returns per-item results, an object with success/failure counts or per-id status).

Error responses

Status	Condition
400	Missing or invalid payload; or one or more compensation_ids not found / not eligible (ticket not Solved or compensation not ACCEPTED).
401	Missing or invalid auth.

Behavior summary

For each valid compensation_id:

1. Debit client balance by the compensation's approved amount (via existing chargeback logic).
2. Create surcharge (NEGATIVE) for the chargeback.
3. Update compensation: status → CHARGEBACK, carrier_payment_status → UNPAID, and chargeback fields.
4. Update ticket: ticket_status_id → DECLINED.
5. Insert ticket comment and ticket history with review_comment.
6. Create audit record (e.g. compensations_history or adjustments module).

---

GET /overweights (response change)

To support chargeback in the UI, the overweights list may include per-row data when the ticket is Solved:

Field	Type	Description
compensation_id	number	Present when the row's ticket has status ACCEPTED and there is an accepted compensation for that ticket. Frontend uses this to build compensation_ids for POST /overweights/chargeback.
compensation_status	string	Optional; if needed for UI to show only ACCEPTED rows as eligible.