Payment Chargebacks

When a cardholder disputes a payment that funded a company's Envia balance, Admin can see the case on Chargebacks (/chargebacks) and, if needed, register or close it by spreadsheet.

This is not Overweights Chargeback (taking back an overweight refund). That flow lives on the Overweights screen.

won means Envia won the dispute (the payment stands). lost means Envia lost (the bank refunded the cardholder). If Envia lost and we also returned the frozen wallet credit, the company would keep both the bank refund and the Envia balance.

What You Can Do

• Browse disputes (automatic from EcartPay and manual from CSV).
• Upload a CSV to register disputes that did not arrive by webhook.
• Preview valid vs invalid rows before anything is saved.
• Apply the valid rows: status starts as created and the company balance is frozen.
• Close Stripe/PayPal rows that are still created as won (unfreeze) or lost (keep the freeze).
• Open More for customer data, payments, surcharges, documents, and error logs.

Getting There

Open Chargebacks from the main navigation (/chargebacks).

You need chargebacks-index to see the page. You need chargebacks-management to upload CSV or mark won/lost.

How a dispute appears

Automatic (usual)

EcartPay notifies the queries service. The row appears on this screen with a hold already applied. Status can move to pending, in review, won, or lost by itself. You do not upload a file for these.

Manual (CSV)

Use this when operations must register the dispute from a file.

Common Tasks

Uploading a CSV (register)

1. Click Upload file.
2. Use a template with columns: transaction_reference, order_date, expiration_at, reason.
   • order_date is the payment date in EcartPay (not the dispute deadline).
3. Drop the file (max 100 rows).
4. Review the preview:
   • Success — will be registered if you apply.
   • Errors — skipped (empty order_date, transaction not found, already exists, amounts do not match, gateway ecartpay, and similar).
5. Confirm Apply. Each success row is saved as created and the disputed amount is frozen on the company.

Nothing is saved until you apply. Closing the preview cancels the batch.

Closing a manual dispute (won / lost)

1. Only rows with status created and gateway Stripe or PayPal have an enabled checkbox.
2. Select one or more rows (or use the header checkbox for eligible rows on the page).
3. Click the bulk Apply chargebacks action.
4. Choose won or lost and confirm.

You choose	Meaning	Balance
Won	Envia won	Frozen amount is returned to the company
Lost	Envia lost	Freeze stays (bank already refunded the card)

You cannot close pending / in review / already won or lost rows from this bulk action.

Opening detail

Click More on a row. Use the tabs for documents, related payments, surcharges (hold/release), and error logs (usually empty if nothing failed).

Frequently Asked Questions

Why was a transaction not found if I know it exists in EcartPay?

order_date must be the payment date. Search uses that day plus one day before and after. A missing or wrong order_date looks like "not found".

Why is gateway "ecartpay" an error if the row was found?

The file layout is for manual Stripe/PayPal disputes. The system found the payment but will not register that gateway here, because this screen cannot close those rows as won/lost.

Do I use this screen for overweight refunds?

No. Use Overweights and the Overweights Chargeback guide.

Who freezes the money on automatic disputes?

The queries webhook, when EcartPay sends chargebacks.create. This screen only displays those rows unless you also use CSV.