Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 38 ยท Testing and Fraud

Disputes and Chargebacks

Learn the lifecycle of a card dispute, the dispute webhooks and statuses, what evidence wins, deadlines and fees, and how to reduce chargebacks with clear billing descriptors and refunds.

A dispute (also called a chargeback) happens when a cardholder tells their bank that a payment is wrong: "I did not make this purchase", "I never received the item", "I was charged twice". The bank reverses the money immediately and asks you to prove the charge was legitimate. Disputes are a normal cost of selling online, but too many of them damage your standing with card networks, so every merchant needs a process.

The lifecycle

flowchart LR
  A["Customer disputes"] --> B["Funds withdrawn + fee"]
  B --> C["You submit evidence"]
  C --> D{"Bank decides"}
  D -- won --> E["Funds returned"]
  D -- lost --> F["Funds stay with customer"]
  B -.->|"no response"| F

Money leaves first; you win it back only with evidence.

  1. The disputed amount, plus a dispute fee, is taken from your balance at once.
  2. Stripe sends charge.dispute.created with status needs_response and an evidence_details.due_by deadline.
  3. You gather and submit evidence before the deadline. Missing it means an automatic loss.
  4. The issuing bank reviews it. Stripe sends charge.dispute.closed with status won or lost (earlier you may see under_review).
  5. If you win, the amount is returned; the fee treatment depends on your pricing and region, so read the current Stripe terms.

Some payments can be handled earlier. Inquiries or retrieval requests, and tools such as Visa's or Mastercard's pre-dispute programs, let you refund before a formal chargeback exists. Refunding quickly is often cheaper than fighting.

Reasons and what proves your case

Each dispute has a reason such as fraudulent, product_not_received, duplicate, subscription_canceled or product_unacceptable. Evidence should match the reason:

Reason Useful evidence
fraudulent IP address, device, AVS/CVC results, 3D Secure authentication, prior orders from the same customer
product_not_received Carrier tracking with delivery proof, signature, delivery address
duplicate Records showing the charges were for different orders
subscription_canceled Cancellation policy, proof the customer was warned, usage logs after the cancellation date
product_unacceptable Description at purchase, refund policy, communication history

Payments that were authenticated with 3D Secure usually shift liability for fraud disputes to the issuer, which is a strong reason to use it for risky orders (Strong Customer Authentication).

Handling dispute webhooks

The webhook should alert a human, record the deadline, and optionally gather evidence automatically.

Node.js From dispute event to a case with a deadline

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Building the evidence pack

Gather proof automatically when an order is placed, not in a panic six weeks later. Store IP, user agent, delivery confirmation, the terms the customer accepted and all support messages. Submit through the Dashboard or API.

JavaScript
// Read-only: needs the "stripe" npm package
await stripe.disputes.update('dp_123', {
  evidence: {
    customer_email_address: '[email protected]',
    shipping_carrier: 'UPS',
    shipping_tracking_number: '1Z999AA10123456784',
    shipping_date: '2026-03-02',
    uncategorized_text: 'Delivered 2026-03-05 and signed for. Order history attached.',
  },
  submit: true,
});

You can usually submit evidence once. Write it clearly, attach everything in a single submission, and keep it factual. Never invent or alter evidence.

Node.js Deciding whether to fight a dispute

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Prevention checklist

  • Use a clear statement descriptor so customers recognise the charge on their bill. Many disputes are "I do not know this merchant".
  • Send receipts and shipping notifications; make contact details easy to find.
  • Publish clear refund and cancellation terms; a simple refund is cheaper than a chargeback.
  • Use 3D Secure and Radar for risky payments; verify addresses on physical goods.
  • Watch your dispute rate. Card networks monitor it, and sustained high levels can mean fines or loss of processing.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to the money when a dispute is opened?

    The funds and a dispute fee are withdrawn immediately; you win them back only if the bank rules for you.
  2. 2. What happens if you do not respond before due_by?

    No response means no evidence, so the dispute is lost.
  3. 3. Which evidence best fits product_not_received?

    Delivery confirmation to the customer's address directly answers the claim.
  4. 4. Why is a clear statement descriptor useful?

    Unrecognised charges are a leading cause of disputes.

Summary

  • A dispute reverses funds at once and requires you to prove the sale was legitimate.
  • Respond before due_by with evidence that matches the dispute reason.
  • Handle charge.dispute.created and charge.dispute.closed webhooks.
  • Prevent disputes with clear descriptors, receipts, refunds and 3D Secure.

Next: PCI DSS and Staying Out of Scope