Skip to main content

Fee Calculation & Examples

The Fee Formula​

Every Standard Fee Configuration uses the same calculation:

fee = (payment_amount_cents x rate_as_decimal) + transaction_fee_cents

Where rate_as_decimal = variable_rate / 100. A variable_rate of 2.75 means 2.75%, so rate_as_decimal = 0.0275.

If fee_cap_cents is set:

fee = min(calculated_fee, fee_cap_cents)

Breaking it down​

ParameterWhat It DoesExample
variable_ratePercentage rate. 2.75 = 2.75%10000 x 0.0275 = 275 cents
transaction_fee_centsFlat fee added per transaction+ 25 cents
fee_cap_centsMaximum fee (if set)min(300, 1000) = 300 cents

Example: A $100.00 payment with a config of variable_rate: 2.75, transaction_fee_cents: 25:

fee = (10000 x 0.0275) + 25
fee = 275 + 25
fee = 300 cents = $3.00

If fee_cap_cents: 250 were set, the fee would be capped at $2.50 instead.

When the variable rate calculation produces a fractional cent, the result is rounded to the nearest cent using standard rounding (half-up). For example, a $33.33 payment at 2.75% produces 91.6575 cents, which rounds to 92 cents.

Interactive Fee Calculator​

Use this calculator to configure fee rates and see exactly which configuration applies for each payment type. Toggle brand-specific configurations on and off to see the hierarchical selection in action.

Base Processing Fees
Online payments (processing_ecomm)%centscents
Terminal payments (processing_card_present)%centscents
ACH payments (processing_ach)%centscents
Expedited ACH payments (processing_ach_expedited)%centscents
Brand-Specific Fees (optional)
Visa online (visa_brand_ecomm)%centscents
Visa terminal (visa_brand_card_present)%centscents
Mastercard online (mastercard_brand_ecomm)%centscents
Mastercard terminal (mastercard_brand_card_present)%centscents
Amex online (amex_brand_ecomm)%centscents
Amex terminal (amex_brand_card_present)%centscents
Discover online (discover_brand_ecomm)%centscents
Discover terminal (discover_brand_card_present)%centscents
Platform Fee (optional)
Platform fee (platform)%centscents
Payment Simulation
$
Payment TypeConfig UsedProcessing FeePlatform FeeTotal Fee
Visa onlineprocessing_ecommbase$3.00$1.00$4.00
Visa terminalprocessing_card_presentbase$2.60$1.00$3.60
Mastercard onlineprocessing_ecommbase$3.00$1.00$4.00
Mastercard terminalprocessing_card_presentbase$2.60$1.00$3.60
Amex onlineamex_brand_ecommbrand$3.50$1.00$4.50
Amex terminalprocessing_card_presentbase$2.60$1.00$3.60
Discover onlineprocessing_ecommbase$3.00$1.00$4.00
Discover terminalprocessing_card_presentbase$2.60$1.00$3.60
What to Try
  1. Enable amex_brand_ecomm and notice how Amex online payments switch from the base processing_ecomm to the brand-specific config
  2. Disable it and watch Amex fall back to processing_ecomm
  3. Toggle the platform fee on and off to see it applied across all payment types
  4. Set a fee_cap_cents on a base processing config and increase the payment amount to see the cap in effect

Walkthrough: Set Fee Configurations on a Sub Account​

This walkthrough covers a common setup from start to finish.

Step 1: Configure base processing fees​

First, set up the rates that will apply to most payments:

POST /v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm
{
  "variable_rate": 2.75,
  "transaction_fee_cents": 25
}
POST /v1/sub_accounts/acc_xxx/fee_configurations/processing_card_present
{
  "variable_rate": 2.50,
  "transaction_fee_cents": 10
}

Now the sub account can process card-not-present payments at 2.75% + $0.25 and terminal payments at 2.50% + $0.10.

Step 2: Add brand-specific pricing for Amex​

Amex interchange is typically higher, so platforms often pass that along:

POST /v1/sub_accounts/acc_xxx/fee_configurations/amex_brand_ecomm
{
  "variable_rate": 3.25,
  "transaction_fee_cents": 25
}

Amex online payments are now charged 3.25% + $0.25. All other brands still use the base 2.75% + $0.25.

Step 3: Add a platform fee​

POST /v1/sub_accounts/acc_xxx/fee_configurations/platform
{
  "variable_rate": 1.00
}

Every payment now also includes a 1.00% platform fee.

Step 4: Process a payment​

Create a payment without passing any fee parameters in the request and using an Amex payment method (for testing you can use the test card number 378282246310005 - see the testing section for more test payment method options):

POST /v1/payments
{
  "amount": 10000,
  "currency": "usd",
  "payment_method": {
    "token": "pm_xxx"
  }
}

The system detects the card brand and applies the right configuration automatically. For a $100 Amex payment:

  • Processing fee: amex_brand_ecomm at 3.25% + $0.25 = $3.50
  • Platform fee: platform at 1.00% = $1.00
  • Total fees: $4.50
Fees Are Not in the Create Payment or Checkout Event Responses

The fee breakdown is not included in the create payment response or in checkout events (checkout.created, checkout.completed, checkout.completion.succeeded). SFC fees are calculated after the payment is created. Subscribe to payment events (webhooks) (payment.created, payment.succeeded, etc.) or use the get payment API to receive the finalized fee details.

All payment events (payment.created, payment.updated, etc.) include the fee breakdown:

{
  "id": "py_xxx",
  "amount": 10000,
  "fee_amount": 450,
  "fees": [
    {
      "id": "pyfee_1",
      "type": "processing_fee",
      "amount": 350,
      "remaining_amount": 350,
      "currency": "usd",
      "source_configuration_id": "sfc_abc123",
      "source_fee_type": "amex_brand_ecomm"
    },
    {
      "id": "pyfee_2",
      "type": "platform_fee",
      "amount": 100,
      "remaining_amount": 100,
      "currency": "usd",
      "source_configuration_id": "sfc_def456",
      "source_fee_type": "platform"
    }
  ]
}

For the same $100 amount with a Visa card (for testing you can use the test card number 4242424242424242 - see the testing section for more test payment method options):

  • Processing fee: processing_ecomm at 2.75% + $0.25 = $3.00 (no Visa-specific config, falls back to base)
  • Platform fee: platform at 1.00% = $1.00
  • Total fees: $4.00

Overriding Auto-Calculated Fees​

Any auto-calculated fee can be overridden by passing explicit fees in the payment request. This is useful for one-off adjustments — for example, waiving the platform fee on a specific payment. Only the fee types you include in the fees array are overridden — everything else is calculated based on the fee configurations set on the sub account.

Pass the fees array with the fee type and amount to override:

POST /v1/payments
{
  "amount": 10000,
  "currency": "usd",
  "payment_method": {
    "token": "pm_xxx"
  },
  "fees": [
    { "type": "platform_fee", "amount": 0 }
  ]
}

In this example, the processing fee is still auto-calculated from the configuration, but the platform fee is explicitly set to $0.

The payment event reflects the override:

{
  "id": "py_xxx",
  "amount": 10000,
  "fee_amount": 350,
  "fees": [
    {
      "id": "pyfee_1",
      "type": "processing_fee",
      "amount": 350,
      "remaining_amount": 350,
      "currency": "usd",
      "source_configuration_id": "sfc_abc123",
      "source_fee_type": "amex_brand_ecomm"
    },
    {
      "id": "pyfee_2",
      "type": "platform_fee",
      "amount": 0,
      "remaining_amount": 0,
      "currency": "usd",
      "source_configuration_id": null,
      "source_fee_type": null
    }
  ]
}

source_configuration_id and source_fee_type are null when the fee was explicitly passed in the payload.

Scenario Reference​

Card-not-present (ecomm) payments​

Card BrandBrand Config Exists?Config UsedResult
VisaNo visa_brand_ecommprocessing_ecommBase rate applied
VisaYes visa_brand_ecommvisa_brand_ecommBrand rate applied
MastercardNo mastercard_brand_ecommprocessing_ecommBase rate applied
MastercardYes mastercard_brand_ecommmastercard_brand_ecommBrand rate applied
AmexNo amex_brand_ecommprocessing_ecommBase rate applied
AmexYes amex_brand_ecommamex_brand_ecommBrand rate applied
DiscoverNo discover_brand_ecommprocessing_ecommBase rate applied
DiscoverYes discover_brand_ecommdiscover_brand_ecommBrand rate applied

Card-present (terminal) payments​

Card BrandBrand Config Exists?Config UsedResult
VisaNo visa_brand_card_presentprocessing_card_presentBase rate applied
VisaYes visa_brand_card_presentvisa_brand_card_presentBrand rate applied
MastercardNo mastercard_brand_card_presentprocessing_card_presentBase rate applied
MastercardYes mastercard_brand_card_presentmastercard_brand_card_presentBrand rate applied
AmexNo amex_brand_card_presentprocessing_card_presentBase rate applied
AmexYes amex_brand_card_presentamex_brand_card_presentBrand rate applied
DiscoverNo discover_brand_card_presentprocessing_card_presentBase rate applied
DiscoverYes discover_brand_card_presentdiscover_brand_card_presentBrand rate applied

ACH payments​

ACH payments do not have brand-specific configurations. The base processing config is always used.

Payment TypeConfig Used
Standard ACHprocessing_ach
Expedited ACHprocessing_ach_expedited

Platform fee​

The platform configuration applies to all payment types when configured. It is added alongside the processing fee, not in place of it.

Common Mistakes​

Thinking brand configs stack on top of base configs​

Brand-specific configurations replace the base processing config for that brand — they do not add to it. If processing_ecomm is 2.75% and visa_brand_ecomm is 0.50%, Visa payments are charged 0.50%, not 3.25%.

Setting brand configs without a base config​

Brand-specific configs only apply to their specific brand. Every other card brand still needs a base processing config. The API enforces this — if you try to create a brand-specific config (e.g., amex_brand_ecomm) without an active base processing config for that payment type (e.g., processing_ecomm), the request will fail with a fee_type_must_be_inside_hierarchy error. Always set up your base configs (processing_ecomm, processing_card_present) first.

Forgetting that fee caps apply per-config​

If processing_ecomm has fee_cap_cents: 500 and amex_brand_ecomm has no cap, the $5.00 cap only applies to non-Amex payments. Each configuration's cap is independent.

Next Steps​