Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 38 ยท Compliance and Patterns

Refunds, Tax and Invoices

Handle full and partial refunds in integer cents, understand sales tax, VAT and Stripe Tax at a practical level, and generate clear invoices and receipts with correct totals and rounding.

Taking money is half of commerce. Giving it back correctly, charging the right tax and producing a document the customer and an accountant can understand are the other half. This lesson covers refunds, tax and invoices, with integer arithmetic you can check yourself. It is general information, not tax advice; tax rules vary by country and change often, so consult a professional and Stripe's current documentation.

Refunds

A refund returns money for a payment. With Stripe you refund a PaymentIntent or charge, fully or partially, as many times as you like until the total reaches the captured amount.

JavaScript
// Read-only: needs the "stripe" npm package
await stripe.refunds.create({
  payment_intent: 'pi_123',
  amount: 1500,                 // omit for a full refund
  reason: 'requested_by_customer',
  metadata: { order_id: '1042', note: 'item damaged' },
}, { idempotencyKey: 'refund-1042-damaged' });

Key facts:

  • Refunds go to the original payment method and may take several days to appear on a statement.
  • Stripe usually does not return its processing fee on a refund; check current pricing.
  • A refund can fail (closed card, for example); Stripe then pays the money back another way and emits refund.failed. Listen to refund.created, refund.updated and charge.refunded.
  • Use an idempotency key so a retry cannot refund twice.
  • Disputes and refunds are different: if you refund, the customer should not also dispute, so refund before they do.
Node.js A refund tracker that never over-refunds

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.

Sales tax, VAT and GST

Tax types differ by place:

  • US sales tax: set by state and often by city or county; collected from the buyer at checkout. You usually must collect it where you have nexus (a sufficient presence or sales volume).
  • VAT (EU, UK and others) and GST: a tax on value added at each stage, shown on the invoice; businesses can often reclaim the VAT they pay. Rates differ per country and per product type; selling digital goods to consumers uses the buyer's country rate.
  • Reverse charge: for some business-to-business sales the buyer, not you, accounts for the VAT.

Calculating all of this yourself is difficult. Stripe Tax can calculate and collect the right tax from the customer's location, product tax code and your registrations, and produces reports. You still decide where to register and file. Whether tax is inclusive (the price already contains it) or exclusive (added on top) is a product decision.

Node.js Tax exclusive versus inclusive

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.

In the inclusive case the tax is computed as gross - net so the parts always sum to the price the customer saw.

Invoices

An invoice is a document listing what was sold, quantities, unit prices, discounts, tax and the total due. Stripe's Invoicing creates hosted invoice pages and PDFs, numbers them sequentially and emails them. Subscriptions generate invoices automatically. Many countries require specific fields: your legal name and address, a tax id, an invoice number and date, and the customer's details. Receipts, by contrast, are simpler confirmations of payment.

Per line, compute totals in cents and sum them; avoid rounding each line differently from the total.

Node.js Building an invoice with tax per line

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.

Currency and rounding details

  • Zero-decimal currencies such as JPY have no minor unit: amount: 500 means 500 yen, not 5 yen. Three-decimal currencies exist too. Always use a helper that knows the currency's exponent.
  • Keep a single rounding policy and document it. Accountants hate pennies that disappear.
  • Store the currency next to every amount. A number without a currency is a bug waiting to happen.

Never divide money by 100 with floating-point arithmetic and then store the result. Keep integers in your database and format only for display.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many times can a payment be partially refunded?

    Partial refunds can be repeated until the full amount has been returned.
  2. 2. Why use an idempotency key when creating a refund?

    If a request times out and is retried, the same key returns the original result instead of a second refund.
  3. 3. A price of 120.00 includes 20 percent tax. What is the net amount?

    Gross 120.00 divided by 1.20 is 100.00, so tax is 20.00.
  4. 4. Which statement about currencies is correct?

    Stripe amounts use the smallest currency unit, which differs between currencies.

Summary

  • Refund by PaymentIntent, partially or fully, with an idempotency key; expect delays.
  • Tax depends on location and product; Stripe Tax helps, but you remain responsible.
  • Invoices need sequential numbers, legal details and consistent per-line math.
  • Store integer amounts with a currency and mind zero-decimal currencies.

Next: Project: A Webhook Processor