API Documentation

Stripe Fees API · Last updated 2026-04-12

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-04-12",
  "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

POST/api/calculate-multihop

Calculate total fees for a multi-hop transfer chain (e.g., Connected Account → Platform → Connected Account → Bank). Each leg is calculated sequentially, with the output of one leg becoming the input of the next.

Request Body

Parameter	Type	Required	Description
`initialAmount`	`number`	required	Starting transfer amount in dollars (must be > 0)
`legs`	`array`	required	Non-empty array of transfer legs
`legs[].label`	`string`	required	Description of this leg (e.g., "Org to Platform")
`legs[].paymentMethodId`	`string`	required	Payment method ID for this leg (use Connect method IDs)
`legs[].modifiers`	`string[]`	optional	Modifier IDs to apply to this leg (e.g., connect_cross_border)

Example Request

curl -X POST https://stripe.butchernetwork.com/api/calculate-multihop \
  -H "Content-Type: application/json" \
  -d '{
    "initialAmount": 1000,
    "legs": [
      { "label": "Org account debit to Platform", "paymentMethodId": "connect_account_debit" },
      { "label": "Platform transfer to Agent", "paymentMethodId": "connect_platform_transfer" },
      { "label": "Agent payout to bank", "paymentMethodId": "connect_standard_payout" }
    ]
  }'

Response

{
  "initialAmount": 1000,
  "legs": [
    {
      "label": "Org account debit to Platform",
      "paymentMethodName": "Account Debit / Platform Transfer",
      "inputAmount": 1000,
      "fee": 15.00,
      "feeLabel": "1.5%",
      "outputAmount": 985.00
    },
    {
      "label": "Platform transfer to Agent",
      "paymentMethodName": "Platform Transfer Out",
      "inputAmount": 985.00,
      "fee": 0,
      "feeLabel": "$0.00 flat",
      "outputAmount": 985.00
    },
    {
      "label": "Agent payout to bank",
      "paymentMethodName": "Standard Payout",
      "inputAmount": 985.00,
      "fee": 2.71,
      "feeLabel": "0.25% + $0.25",
      "outputAmount": 982.29
    }
  ],
  "totalFees": 17.71,
  "finalAmount": 982.29,
  "effectiveRate": 1.77
}

Error Responses

400Missing/empty legs array, missing initialAmount, or invalid paymentMethodId

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	5.99% + $0.30
`stablecoin`	Stablecoin Payment	1.5%
`connect_standard_payout`	Standard Payout	0.25% + $0.25
`connect_instant_payout`	Instant Payout	1.5% ($0.50 min)
`connect_account_debit`	Account Debit / Platform Transfer	1.5%
`connect_platform_transfer`	Platform Transfer Out	Free

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%
`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
`connect_cross_border`	Standard Payout	Cross-border transfer	+0.25%
`fx_usd_eur_gbp`	Standard Payout	FX conversion (USD/EUR/GBP)	+0.5%
`fx_other_us_sender`	Standard Payout	FX conversion (other currencies, US sender)	+1%
`fx_other_non_us`	Standard Payout	FX conversion (other currencies, non-US sender)	+2%
`connect_cross_border`	Instant Payout	Cross-border transfer	+0.25%
`fx_usd_eur_gbp`	Instant Payout	FX conversion (USD/EUR/GBP)	+0.5%
`fx_other_us_sender`	Instant Payout	FX conversion (other currencies, US sender)	+1%
`fx_other_non_us`	Instant Payout	FX conversion (other currencies, non-US sender)	+2%
`connect_cross_border`	Account Debit / Platform Transfer	Cross-border transfer	+0.25%

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 & Metered)	0.7% of billing volume
`tax`	Stripe Tax	0.5% per transaction

Notes on Stripe Billing & Metered Billing

The billing add-on (0.7%) applies to all Stripe Billing volume: fixed-price subscriptions, metered/usage-based billing, tiered pricing, and recurring invoices.
Stripe does not charge per-event or per-meter fees for reporting usage via the Meters API or legacy Usage Records API.
As of July 2024, Stripe consolidated the former Starter (0.5%) and Scale (0.8%) tiers into a single Billing plan at 0.7%.
The tax add-on (0.5%) is for Stripe Tax, which automatically calculates and collects sales tax, VAT, and GST. This is independent of Billing.

Fees sourced from stripe.com/pricing · Last updated 2026-04-12