Skip to main content

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​

SourceWhat happens
Razorpay webhook POST /api/webhooks/razorpay/disputesChecks 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/disputesCatches 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 fieldFromNotes
billing_proofThe stored GST invoice (InvoicesService.pdfBuffer), otherwise an order recordAn invoice counts only if it is this order's and has lines.
shipping_proofMedusa fulfilment shipped_at / delivered_at, the AWB, and the courier's scans from the courier.tracking_updated outbox rowsThere is no photo proof of delivery.
proof_of_serviceService 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_communicationMessages we sent about the order (notification_logs by order id) and the customer's chatsEmails and phone numbers are masked.
explanation_letterThe chosen draftAlways 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​

  1. 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).

  2. The AI draft (ChatService, the deployed chain) rewrites the standard draft. It is kept only if it passes checkDraft, 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​

ButtonWhat it does
Send to the customerEmails 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 draftUploads 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 RazorpayThe 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 chargebackPOST /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)​

  1. 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 reuse RAZORPAY_WEBHOOK_SECRET.
  2. The Razorpay keys (RAZORPAY_KEY_ID / RAZORPAY_KEY_SECRET) already reach the API pod.
  3. Staff who handle chargebacks need the finance_admin or super_admin role.

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.