Chargebacks — evidence agent and Razorpay filing
When a customer disputes a payment with their bank, the dispute appears in the staff console under Admin → Chargebacks. An agent gathers the evidence from our own records and drafts the answer. Staff review it, email the customer if it helps, and file the answer with Razorpay. Nothing goes to a customer or the bank until someone presses the button, and every button shows the exact text first.
Code: apps/api/src/chargebacks/ (API) and apps/storefront/app/account/admin/chargebacks/ (console).
How a dispute arrives
| Source | What happens |
|---|---|
Razorpay webhook POST /api/webhooks/razorpay/disputes | Checks the raw-body HMAC, then publishes payment.dispute_updated (event id = Razorpay's x-razorpay-event-id) and returns 200. The handler creates or updates the case. |
Half-hourly poll of GET /v1/disputes | Catches a webhook that never came, or whose handler failed (the event bus doesn't retry handlers). Check Razorpay now runs it on demand. |
| Add a PayU / CCAvenue dispute (console) | PayU and CCAvenue have no disputes API, so their disputes are typed in from the dashboard or email. |
Each case is kept once per processor and dispute id. A retried webhook is applied once, and an older event never moves the status back.
What the agent gathers
All of it is read-only. A source that is missing or failing becomes a gap shown on the case, never an error.
| Razorpay field | From | Notes |
|---|---|---|
billing_proof | The stored GST invoice (InvoicesService.pdfBuffer), otherwise an order record | An invoice counts only if it is this order's and has lines. |
shipping_proof | Medusa fulfilment shipped_at / delivered_at, the AWB, and the courier's scans from the courier.tracking_updated outbox rows | There is no photo proof of delivery. |
proof_of_service | Service tickets and visits for the customer since the order: checklist, photos taken, signature, and OTP-verified sign-off. Warranty registrations by their account. | Tickets carry no order id, so they are matched by the customer's email or phone. |
customer_communication | Messages we sent about the order (notification_logs by order id) and the customer's chats | Emails and phone numbers are masked. |
explanation_letter | The chosen draft | Always filed. |
How a payment is tied to its order: Razorpay's payment email, then the customer's Medusa orders, then
the order whose metadata.payment_ref is that payment id. When that fails, an admin links the order by
hand on the case.
The drafts
-
The standard draft is written by code from the facts alone, so there is always an answer even when every AI provider is down. It recommends contest, accept (nothing shows the order left us) or a person decides (test orders, later dispute phases, product-quality or refund claims).
-
The AI draft (
ChatService, the deployed chain) rewrites the standard draft. It is kept only if it passescheckDraft, otherwise the standard draft stands:- every quote, rupee amount and date must be in the record;
- the merchant is named only as "UTL Solar, the merchant";
- no apology, no refund promise, no he/she;
- a card rule (Visa 13.1, Mastercard 4853) is cited only for that network;
- no delivery or installation is claimed that the record doesn't show;
- the summary is at most 1,000 characters.
The AI gets the customer's first name and city only, never their email, phone or address.
Staff can switch drafts, edit the summary and the customer email (the checker's warnings show as they type), leave a file out, or gather the evidence and redraft with a note.
The buttons
| Button | What it does |
|---|---|
| Send to the customer | Emails the drafted note: what our records show, and a request to withdraw the dispute if it was raised by mistake. Sent once (sendOnce key chargeback:<dispute>:customer-email). A press at night is held until 8 am India time. |
| Save on Razorpay as a draft | Uploads one PDF per field (POST /v1/documents, dispute_evidence), then PATCH /v1/disputes/:id/contest with action: draft. Nothing goes to the bank. |
| File with Razorpay | The same with action: submit, which is final. The dispute is then read back: anything Razorpay doesn't show is listed as a warning, because Razorpay has silently dropped a file before (Vendeye, 2026-10). |
| Accept the chargeback | POST /v1/disputes/:id/accept. Irreversible: Razorpay refunds the customer. |
Every press is claimed with one conditional write, so a double click or a second pod can't send or file
twice. Live Razorpay keys file only when NODE_ENV=production; test keys (rzp_test_…) work anywhere.
Finance and super admins get an email when a dispute opens, when its status changes, and 3 days and 24 hours before the deadline.
Setup (owner)
- On the Razorpay dashboard, go to Settings → Webhooks → Add:
- URL:
https://<api host>/api/webhooks/razorpay/disputes - Events:
payment.dispute.created,.under_review,.action_required,.won,.lost,.closed - Secret: put it in
RAZORPAY_DISPUTES_WEBHOOK_SECRET, or leave that empty to reuseRAZORPAY_WEBHOOK_SECRET.
- URL:
- The Razorpay keys (
RAZORPAY_KEY_ID/RAZORPAY_KEY_SECRET) already reach the API pod. - Staff who handle chargebacks need the
finance_adminorsuper_adminrole.
Known gaps
- No published terms, refund or shipping page. The footer links go nowhere, so there is no policy to attach. Banks weigh a policy the customer agreed to at checkout, and checkout records no consent.
- No proof-of-delivery photo or signature from the courier, and no login, IP or device history for fraud claims. An OTP-signed installation is the strongest evidence we hold.
- Visit photos are counted, not attached. Staff have no route to view them yet.
- A lost chargeback doesn't reverse anything else. Loyalty points, technician earnings and the Medusa order stay as they were.