Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 38 ยท Checkout and Payment Intents

Refunds, Disputes and Payouts

Handle money after a payment: issue full and partial refunds, respond to chargebacks with evidence, understand the Stripe balance and payout schedule, and track fees with balance transactions.

Collecting money is half the story. Customers return goods, orders get cancelled, cards get stolen, and at some point the money you earned must reach your bank account. This lesson covers the three after-sale topics every payment integration meets: refunds, disputes (chargebacks) and payouts, plus the balance that ties them together.

Refunds

A refund (re_...) sends money back to the original payment method. You can refund the full amount or part of it, and you can issue several partial refunds as long as their total never exceeds the original charge.

JavaScript
// Real Stripe usage (read-only).
const refund = await stripe.refunds.create({
  payment_intent: "pi_3Ox91Z...",
  amount: 1500,                    // omit to refund everything left
  reason: "requested_by_customer", // or duplicate / fraudulent
  metadata: { return_id: "R-88" },
});

Facts to remember:

  • Refunds usually appear on the customer's statement in 5 to 10 business days, depending on their bank. Tell customers this, or they will contact support after a day.
  • Stripe does not return its processing fee on refunds in many regions (check your pricing terms), so a refund costs you the fee.
  • You can refund a payment for up to about 180 days. After that, send money another way.
  • A refund cannot be undone. Treat the button as destructive and log who pressed it.

A refund also changes your balance: it is debited from what you hold at Stripe. If you have no balance, Stripe debits your bank account for the shortfall.

Node.js Safe refund bookkeeping (stand-in)

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.

Disputes (chargebacks)

A dispute starts when the cardholder asks their bank to reverse a charge, instead of asking you. Reasons include fraud ("I did not make this"), "product not received", "not as described", "duplicate", and "subscription cancelled". The bank immediately withdraws the amount plus a dispute fee from your balance. You then have a window (often about 7 to 21 days) to submit evidence. The bank decides; the outcome is final in most cases.

flowchart LR
  A["Cardholder disputes"] --> B["Funds withdrawn<br/>+ dispute fee"]
  B --> C{"You submit evidence?"}
  C -- "no / lose" --> D["Dispute lost<br/>funds stay with customer"]
  C -- "yes / win" --> E["Dispute won<br/>funds returned"]

You pay the dispute fee even if you win in many cases. Prevention beats fighting.

Webhook events to handle: charge.dispute.created, charge.dispute.updated, charge.dispute.closed. When the first arrives, alert a human, pause fulfilment of the related order if it is not shipped, and gather evidence.

Good evidence includes: proof of delivery with signature or tracking, customer communication, the terms they accepted, usage logs (for software), IP address and device match, previous undisputed orders from the same customer, and a clear refund policy. Upload it through the API (stripe.disputes.update) or the Dashboard before the deadline.

Preventing disputes

Clear descriptor Name on the statement
Receipts Email every purchase
Easy refunds Cheaper than disputes
3D Secure Shifts fraud liability
1 / 2

Too many disputes (the card networks watch the ratio of disputes to transactions, with a threshold around one percent) can bring extra fees and monitoring programs, and in the worst case the loss of your ability to take cards. Track your dispute rate monthly.

The balance

Stripe keeps a balance for your account per currency, split into pending (recent payments that have not cleared) and available (can be paid out). Every movement creates a balance transaction (txn_...) with amount, fee, net, a type (charge, refund, dispute, payout, adjustment) and an available_on date. This is the object your finance team wants, because it reconciles to your bank.

Node.js Reconcile a balance (stand-in)

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.

Payouts

A payout (po_...) moves available balance to your bank account. By default Stripe pays out automatically on a schedule: daily, weekly or monthly, with an initial rolling delay (often 2 to 7 days, longer for new accounts or some countries) between charge and availability. You can switch to manual payouts, or use instant payouts for a fee in supported countries.

Reconciliation tip: one payout equals many charges, refunds and fees. Use the payout reconciliation report or list balance transactions filtered by payout to see exactly what a bank deposit contains. Never try to match a bank line to a single order.

Node.js What is inside a payout? (stand-in)

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.

Putting it into your system

  • Store the PaymentIntent ID on every order, so you can issue refunds without hunting.
  • Handle charge.refunded and charge.dispute.* webhooks, so your records match Stripe's.
  • Make refunds an authorised, logged, idempotent action in your admin area.
  • Reconcile with balance transactions and payout reports, not with individual orders.

You now have the full life of a one-time payment. In the next chapter we repeat the cycle automatically, with prices, subscriptions and invoices: Products and Prices.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You refunded 1500 of a 5000 payment. What is the most you can still refund?

    Total refunds can never exceed the original amount: 5000 - 1500 = 3500.
  2. 2. What happens to funds the moment a dispute is opened?

    Funds are pulled back immediately; if you win, they return.
  3. 3. Which is the best way to match a bank deposit to your sales?

    A payout bundles many transactions. Reports list its contents.
  4. 4. Which webhook tells you a chargeback has started?

    charge.dispute.created fires when the bank opens a dispute.

Summary

  • Refunds can be full or partial and take days to reach the customer; total refunds never exceed the charge.
  • Disputes pull funds back at once and add a fee; gather evidence before the deadline, and prevent them with clear descriptors, receipts and 3D Secure.
  • The balance is split into pending and available; balance transactions explain every movement.
  • Payouts bundle many transactions; reconcile with reports.

Next: Products and Prices