Implementation:Helicone Helicone Stripe Fee Calculator

Knowledge Sources	Helicone
Domains	Billing, Payments, Finance
Last Updated	2026-02-14 06:32 GMT

Overview

A utility module for calculating Stripe payment processing fees based on the standard 3% + $0.30 per transaction model, operating entirely in cents to avoid floating-point precision issues.

Description

The feeCalculator.ts module centralizes all Stripe fee calculations for the Helicone platform. It defines the standard Stripe fee constants (STRIPE_PERCENT_FEE_RATE = 0.03 and STRIPE_FIXED_FEE_CENTS = 30) and provides functions for:

• Forward calculation: calculateStripeFee computes total fees for a given amount and transaction count
• Reverse calculation: reverseCalculateStripeFee derives fees from a gross (charged) amount using the formula fee = (gross - fixed) * rate / (1 + rate) + fixed
• Net amount: calculateNetAmount returns the amount received after Stripe's cut
• Gross from net: calculateGrossFromNet determines how much to charge to receive a desired net amount
• Average fee: calculateAverageFeePerTransaction computes per-transaction fee averages
• Formatting: formatCentsAsDollars and dollarsToCents for currency conversion

All calculations use Math.ceil for rounding to ensure fees are never underestimated.

Usage

Use these utilities anywhere billing or pricing calculations are needed to ensure consistent and accurate Stripe fee handling across the platform.

Code Reference

Source Location

• Repository: Helicone
• File: packages/common/stripe/feeCalculator.ts

Signature

export const STRIPE_PERCENT_FEE_RATE = 0.03;
export const STRIPE_FIXED_FEE_CENTS = 30;

export function calculateStripeFee(amountCents: number, transactionCount?: number): number
export function reverseCalculateStripeFee(amountCents: number, transactionCount?: number): number
export function calculateNetAmount(grossAmountCents: number, transactionCount: number): number
export function calculateGrossFromNet(netAmountCents: number, transactionCount: number): number
export function calculateAverageFeePerTransaction(totalAmountCents: number, transactionCount: number): number
export function formatCentsAsDollars(cents: number, includeSymbol?: boolean): string
export function dollarsToCents(dollars: number): number

Import

import {
  calculateStripeFee,
  reverseCalculateStripeFee,
  calculateNetAmount,
  calculateGrossFromNet,
  formatCentsAsDollars,
  dollarsToCents,
  STRIPE_PERCENT_FEE_RATE,
  STRIPE_FIXED_FEE_CENTS,
} from "@helicone/common/stripe/feeCalculator";

I/O Contract

Function	Parameters	Returns	Description
calculateStripeFee	amountCents: number, transactionCount?: number	number (cents)	Forward fee calculation: ceil(amount * 3%) + ($0.30 * txns)
reverseCalculateStripeFee	amountCents: number, transactionCount?: number	number (cents)	Derive fees from gross amount charged
calculateNetAmount	grossAmountCents: number, transactionCount: number	number (cents)	Returns gross minus fees (amount actually received)
calculateGrossFromNet	netAmountCents: number, transactionCount: number	number (cents)	Determines charge amount to achieve desired net
calculateAverageFeePerTransaction	totalAmountCents: number, transactionCount: number	number (cents)	Average fee per transaction
formatCentsAsDollars	cents: number, includeSymbol?: boolean	string	Formats cents as dollar string (e.g., "$12.50")
dollarsToCents	dollars: number	number	Converts dollars to cents with rounding

Usage Examples

import {
  calculateStripeFee,
  calculateNetAmount,
  calculateGrossFromNet,
  formatCentsAsDollars,
  dollarsToCents,
} from "@helicone/common/stripe/feeCalculator";

// Calculate fees on a $100 charge (10000 cents)
const fee = calculateStripeFee(10000, 1);
// fee = ceil(10000 * 0.03) + 30 = 300 + 30 = 330 cents ($3.30)

// Calculate what customer receives after Stripe
const net = calculateNetAmount(10000, 1);
// net = 10000 - 330 = 9670 cents ($96.70)

// How much to charge to receive exactly $100
const gross = calculateGrossFromNet(10000, 1);
// gross = ceil((10000 + 30) / (1 - 0.03)) = ceil(10340.21) = 10341 cents ($103.41)

// Format for display
formatCentsAsDollars(10000);        // "$100.00"
formatCentsAsDollars(10000, false); // "100.00"

// Convert user input
dollarsToCents(49.99); // 4999

Related Pages

• Principle:Helicone_Helicone_Payment_Processing