API Documentation

Stripe Fees API · Last updated 2026-02-13

Overview

This API provides the current Stripe fee schedule and a calculator endpoint. All endpoints return JSON and support CORS for cross-origin requests from any domain.

Base URL: https://stripe.butchernetwork.com

Authentication: None required

Rate Limiting: None

GET/api/fees

Returns the complete Stripe fee schedule including all payment methods, add-on services, additional fees, and nonprofit overrides. Cached for 1 hour.

Request

No parameters required.

curl https://stripe.butchernetwork.com/api/fees

Response

{
  "lastUpdated": "2026-02-13",
  "stripePricingUrl": "https://stripe.com/pricing",
  "categories": [
    {
      "id": "cards_wallets",
      "name": "Cards & Wallets",
      "description": "Credit cards, debit cards, and digital wallets"
    }
    // ... more categories
  ],
  "paymentMethods": [
    {
      "id": "card_online",
      "name": "Cards & Digital Wallets",
      "description": "Visa, Mastercard, Amex, Discover, Apple Pay, Google Pay",
      "category": "cards_wallets",
      "baseFee": {
        "type": "percentage_plus_fixed",
        "percentageRate": 0.029,
        "fixedCents": 30
      },
      "modifiers": [
        {
          "id": "manually_entered",
          "label": "Manually entered card",
          "additionalPercentage": 0.005
        }
        // ... more modifiers
      ]
    }
    // ... more payment methods
  ],
  "addOns": [
    {
      "id": "invoicing_starter",
      "name": "Invoicing (Starter)",
      "description": "0.4% per paid invoice",
      "percentageRate": 0.004
    }
    // ... more add-ons
  ],
  "additionalFees": [
    {
      "id": "dispute",
      "name": "Dispute (Chargeback)",
      "fee": { "type": "flat_fee", "amountCents": 1500 },
      "description": "$15.00 per dispute (waived if you win)"
    }
    // ... more fees
  ],
  "nonprofitOverrides": { ... }
}

POST/api/calculate

Calculate Stripe fees for a given payment method, amount, and optional modifiers/add-ons. Returns a detailed fee breakdown.

Request Body

Parameter	Type	Required	Description
`paymentMethodId`	`string`	required	The payment method to calculate fees for
`amount`	`number`	required	Transaction amount in dollars (must be > 0)
`modifiers`	`string[]`	optional	Array of modifier IDs to apply (e.g., international, manually_entered)
`addOns`	`string[]`	optional	Array of add-on IDs (e.g., invoicing_starter, billing)
`isNonprofit`	`boolean`	optional	Use nonprofit discounted rates (default: false)

Example Request

curl -X POST https://stripe.butchernetwork.com/api/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethodId": "card_online",
    "amount": 100,
    "modifiers": ["international"],
    "addOns": ["invoicing_starter"]
  }'

Response

{
  "paymentMethodName": "Cards & Digital Wallets",
  "transactionAmount": 100,
  "baseFeeLabel": "2.9% + $0.30",
  "baseFeeAmount": 3.20,
  "modifiers": [
    {
      "label": "International card (+1.5%)",
      "amount": 1.50
    }
  ],
  "addOns": [
    {
      "label": "Invoicing (Starter)",
      "amount": 0.40
    }
  ],
  "totalFee": 5.10,
  "netAmount": 94.90,
  "effectiveRate": 5.10,
  "chargeToNet": 105.38
}

Response Fields

Parameter	Type	Required	Description
`paymentMethodName`	`string`	required	Display name of the payment method
`transactionAmount`	`number`	required	The original transaction amount in dollars
`baseFeeLabel`	`string`	required	Human-readable label for the base fee (e.g., "2.9% + $0.30")
`baseFeeAmount`	`number`	required	Base fee amount in dollars
`modifiers`	`array`	required	Itemized modifier fees with label and amount
`addOns`	`array`	required	Itemized add-on fees with label and amount
`totalFee`	`number`	required	Total Stripe fee in dollars
`netAmount`	`number`	required	Amount the merchant receives after all fees
`effectiveRate`	`number`	required	Effective fee rate as a percentage
`chargeToNet`	`number`	required	Amount to charge the customer so the merchant nets the full transaction amount after all fees

Error Responses

400Missing or invalid paymentMethodId or amount

404Unknown payment method ID

Reference: Valid IDs

Payment Method IDs

ID	Name	Base Fee
`card_online`	Cards & Digital Wallets	2.9% + $0.30
`link_card`	Link (Card Payment)	2.9% + $0.30
`link_instant_bank`	Link (Instant Bank Payment)	2.6% + $0.30
`terminal_card`	In-Person Card & Wallet	2.7% + $0.05
`ach_debit`	ACH Direct Debit	0.8% ($5.00 cap)
`ach_credit`	ACH Credit	$1.00 flat
`wire`	Wire Transfer	$8.00 flat
`klarna`	Klarna	6.0% + $0.30
`stablecoin`	Stablecoin Payment	1.5%

Modifier IDs

Modifiers are method-specific. Only use modifiers that belong to the selected payment method.

ID	Payment Method	Label	Surcharge
`manually_entered`	Cards & Digital Wallets	Manually entered card	+0.5%
`international`	Cards & Digital Wallets	International card	+1.5%
`currency_conversion`	Cards & Digital Wallets	Currency conversion	+1.0%
`terminal_international`	In-Person Card & Wallet	International card	+1.5%
`tap_to_pay`	In-Person Card & Wallet	Tap to Pay	+$0.10
`p2pe`	In-Person Card & Wallet	Point-to-point encryption	+$0.05

Add-on IDs

Add-ons stack on top of any payment method fee.

ID	Name	Fee
`invoicing_starter`	Invoicing (Starter)	0.4% per paid invoice
`invoicing_plus`	Invoicing (Plus)	0.5% per paid invoice
`post_payment_invoice`	Post-Payment Invoice	0.4% per invoice ($2.00 cap)
`billing`	Billing / Subscriptions	0.7% of billing volume

Fees sourced from stripe.com/pricing · Last updated 2026-02-13