stripe-fee-math

A zero-dependency, high-precision minor-unit integer math library for Stripe processing fee calculations, reverse payout netting, and multi-region merchant fee schedules.

Interactive Workbench: Test and simulate Stripe fee breakdowns with real-time gross/net toggles on the FastTools Stripe Fee Calculator.

Why Integer Arithmetic?

Standard IEEE 754 floating-point arithmetic introduces rounding drift in financial calculations (e.g. 0.1 + 0.2 = 0.30000000000000004). stripe-fee-math operates strictly on minor units (integer cents, pence, euro-cents) and basis points (1 bp = 0.01% = 0.0001), ensuring zero precision drift and 100% parity with Stripe's backend billing engine.

Features

• Zero Dependencies: Pure TypeScript, zero external packages, ultra-lightweight (<4KB).
• Forward Fee Calculation: Calculates merchant processing fees, net payout, and effective rate percentage.
• Reverse Netting Calculation: Computes exact charge amount required so that the merchant receives their desired take-home payout after all processing deductions.
• Verified Regional Schedules: Built-in schedules for United States (2.9% + 30¢), United Kingdom (1.5% + 20p), European Union (1.5% + €0.25), Canada (2.9% + C$0.30), and Australia (1.65% + A$0.30).
• Surcharges & Add-ons: Supports international cards (+1.5%), currency conversion (+1.0%), and manual card entry (+0.5%).
• Dual ESM & CommonJS: Full compatibility with modern bundlers and Node.js runtimes.

Installation

npm install stripe-fee-math
# or
yarn add stripe-fee-math
# or
pnpm add stripe-fee-math

Quick Start

1. Forward Calculation (Standard Charge)

import { computeForward, REGIONS } from 'stripe-fee-math';

const result = computeForward({
  amountCents: 10000, // $100.00
  method: REGIONS.US.methods.find(m => m.id === 'card')!,
  surcharges: []
});

console.log(result.feeCents);          // 320 ($3.20 fee)
console.log(result.netCents);          // 9680 ($96.80 net payout)
console.log(result.effectiveRatePct);  // 3.2%

2. Reverse Netting (Invoice / Desired Payout)

import { computeInverse, REGIONS } from 'stripe-fee-math';

// Want to receive exactly $100.00 net payout in your bank account?
const result = computeInverse({
  targetNetCents: 10000,
  method: REGIONS.US.methods.find(m => m.id === 'card')!,
  surcharges: []
});

console.log(result.grossCents); // 10330 (Charge $103.30 to client)
console.log(result.feeCents);   // 330 ($3.30 Stripe fee)
console.log(result.netCents);   // 10000 ($100.00 received)

Interactive Web Utility

For client-side simulations, multi-region comparisons, and instant invoice breakdowns:

👉 FastTools Stripe Fee Calculator

• US Domestic Card Calculator
• UK Card Processing Rates
• EU Single Euro Payments Area
• Canada Interac & Stripe Rates
• Australia Domestic Card Rates
• Reverse Net Payout Calculator

License

MIT © Alfaz Mahmud Rizve • Part of FastTools