Configurable Fees

Overview

Configurable Fees allow platforms to set fee rates for each sub account (merchant) via the Fee Configurations API. When a payment is processed, the system automatically calculates the applicable fees based on the payment's characteristics — card brand, payment method type (ecomm, terminal, ACH), and the configured rates. Fee amounts do not need to be passed with every payment request.

Each fee rate is stored as a Standard Fee Configuration resource. These configurations give platforms centralized control over their fee structure while keeping payment integration simple — configure once, and the fees for every payment for that sub account are handled automatically.

v1 vs v2 Fee Structure

Configurable Fees are part of the v2 fee structure, which replaces the legacy Application Fee Rate model (v1). If your platform currently uses application_fee_amount or application_fee_rate, see Migrating from Application Fees for guidance on transitioning to v2.

Limitations

• USD only. Configurable Fees are not available for Canadian (CAD) processing. This feature is available for US platform accounts only.
• One active config per fee type per sub account. Creating a new configuration for the same fee type automatically retires the previous one.
• Base processing configs cannot be retired. Once a processing_ecomm, processing_card_present, processing_ach, or processing_ach_expedited config is created, it cannot have an effective_end — it must stay active indefinitely. The only way to change rates is to create a new config, which automatically retires the previous one. See Chaining Configurations for details.
• Brand-specific and platform configs can be retired at any time by passing an effective_end parameter when creating a new configuration. Payments for that brand will fall back to the base processing config.
• Fee configurations apply to a sub account, not to the platform. Each sub account is configured individually.
• Cannot be mixed with legacy Application Fees. Once on v2 fees, the application_fee_amount parameter is no longer accepted.

How It Works

1. Configure fee rates for a sub account via the Create Fee Configuration endpoint or through the JustiFi dashboard
2. Process payments as usual — no fee parameters needed in the payment or checkout request
3. Fees are auto-calculated based on the payment's characteristics and your configuration
4. Optionally override any auto-calculated fee by passing explicit fees in the payment or checkout request

Fee Configuration Types

There are three categories of Standard Fee Configurations. Together, they provide precise control over what is charged per payment.

Base Processing Fees

These define the default fee for each payment method type. You only need to configure the ones relevant to your sub account — for example, if a sub account only processes online card payments, you only need processing_ecomm. Once configured, these types cannot be retired (see Limitations).

Fee Type	When Applied
processing_ecomm	Card-not-present (online) card payments
processing_card_present	Card-present (terminal) card payments
processing_ach	ACH (bank account) payments
processing_ach_expedited	Expedited ACH (bank account) payments

Brand-Specific Fees

These are optional and allow different rates for specific card brands. When a brand-specific configuration exists, it replaces the base processing fee for that brand — it does not stack on top of it.

Fee Type	When Applied
visa_brand_ecomm	Visa online payments
visa_brand_card_present	Visa terminal payments
mastercard_brand_ecomm	Mastercard online payments
mastercard_brand_card_present	Mastercard terminal payments
amex_brand_ecomm	Amex online payments
amex_brand_card_present	Amex terminal payments
discover_brand_ecomm	Discover online payments
discover_brand_card_present	Discover terminal payments

Platform Fee

This is optional and applies to all payments for the sub account, regardless of payment method or card brand. Use this to charge a separate platform service fee alongside the processing fee.

Fee Type	When Applied
platform	All payments (if configured)

Hierarchical Fee Selection

When a payment is processed, the system selects which configuration to use based on a simple hierarchy:

1. Check for a brand-specific config that matches the card brand and payment type
2. If none exists, fall back to the base processing config for that payment type
3. Add platform fee if a platform configuration exists

Brand Configs Replace Base Processing Fees

A brand-specific configuration is the complete processing rate for that brand and payment type. If you configure visa_brand_ecomm at 2.50% + $0.20, that is the full processing fee for Visa online payments — the processing_ecomm rate is not applied on top of it.

Example: How Selection Works

Suppose a sub account is configured with:

• processing_ecomm: 2.75% + $0.25
• amex_brand_ecomm: 3.25% + $0.25
• platform: 1.00%

Incoming Payment	Config Used	Why
$100 Visa online	processing_ecomm	No Visa-specific config exists, base config is applied
$100 Amex online	amex_brand_ecomm	Amex-specific config exists, replaces base config
$100 Mastercard online	processing_ecomm	No Mastercard-specific config exists, base config is applied

In all three cases, the platform fee is additionally applied because it is configured.

See Fee Calculation & Examples for detailed breakdowns with calculated amounts.

Resulting Payment Fees

Regardless of which configuration type is used, the resulting fees on a payment are always one or both of:

• processing_fee — calculated from either a brand-specific or base processing configuration
• platform_fee — calculated from the platform configuration (if it exists)

The configuration type determines how the fee is calculated. The payment fee type is always processing_fee or platform_fee.

Testing and Activation

Getting Started

Configurable Fees are available in test mode for all platforms. To enable configurable fees for live payments, contact customer_success@justifi.tech.

• Test mode: Create standard fee configurations via the create fee configuration API for a test sub account and process test payments with auto-calculated fees. Use this to validate your setup before going live.
• Live mode: Requires enabling the v2 fee structure on your platform settings. Once enabled, fee configurations take effect for all payments on configured sub accounts.

Fees in Payment Responses

Where to Find Fee Data

When using Standard Fee Configurations (SFC), fees are calculated and applied by the payment system after the payment is created. This means:

• Create Payment and Complete Checkout synchronous responses may return an empty fees array.
• Checkout events (checkout.created, checkout.completed, checkout.completion.succeeded) do not include SFC-calculated fees. Checkout events only contain fees that were explicitly passed in the checkout creation request.
• Payment events (payment.created, payment.succeeded, etc.) are the authoritative source for the finalized fee breakdown, including which configuration was used and the calculated amounts.

Subscribe to payment events (webhooks) or use the Get Payment API to retrieve the complete fee details.

All payment events (payment.created, payment.succeeded, etc.) include the fees array with each fee's id, type, amount, remaining_amount, currency, source_configuration_id, and source_fee_type.

Refunds and Fee Returns

When refunding a payment, platforms can choose exactly which fees to return and how much of each. Fee refunds are explicit, not automatic — the fee type and amount to return are specified in the refund request.

{
  "amount": 5000,
  "fees": [
    { "type": "processing_fee", "amount": 175 },
    { "type": "platform_fee", "amount": 50 }
  ]
}

Each fee on a payment tracks a remaining_amount that decreases as fees are returned through refunds. The returned amount cannot exceed the remaining amount on a fee.

This provides full control over fee refund policy — return all fees, return only the platform fee, or return nothing.

Migrating from Application Fees

Configurable Fees (v2 fee structure) replace the legacy application fee rate model (v1). The table below summarizes the key differences:

	v1 (Application Fees)	v2 (Configurable Fees)
How fees are set	application_fee_rate on the sub account, or application_fee_amount per payment request	Standard Fee Configurations per sub account, or explicit fees array per payment request
Fee granularity	Separate rate by payment method type (card vs ACH)	Separate rates by payment type, card brand, and platform fee
Fee on payment record	application_fee field	fees array with processing_fee and platform_fee
Refund control	No fee refund to sub account	Selective — choose which fees to return and how much

Migration Steps

1. Set up fee configurations in test mode. Create Standard Fee Configurations for each sub account that mirror your current application fee rates. See Managing Fee Configurations for API details.
2. Update your payment integration. Remove any application_fee_amount parameters from your payment requests. If you use the application_fee field in payment responses and payment events, switch to reading from the fees array instead.
3. Update refund handling. If you currently rely on automatic proportional fee refunds, update your refund requests to use the explicit fees array. See Refunds and Fee Returns above.
4. Test end-to-end. Process test payments and refunds to confirm fees are calculated correctly and your integration reads from the right response fields.
5. Enable v2 for live payments. Contact customer_success@justifi.tech to enable the v2 fee structure on your platform. Once enabled, fee configurations take effect for all payments on configured sub accounts.

Breaking Changes on v2

Once a platform is on the v2 fee structure:

• The application_fee_amount parameter is no longer accepted on live payment requests — the payment will be rejected with an application_fee_amount_not_allowed_for_v2_fee_structure error
• For checkouts, using application_fees will cause the underlying payment to fail when it is processed, since the checkout submits application_fee_amount to the payments API. Use payment.fees on checkouts instead
• The application_fee field in payment responses will no longer be populated
• Use the fees array for both payments and checkouts instead

Note: In test mode, application_fee_amount is still accepted on v2 accounts to support migration testing. This relaxation does not apply to live payments.

Authentication

Fee configuration endpoints require a platform API key with admin access. Platforms manage fee configurations for their sub accounts using their platform credentials. See Authentication for details on obtaining and using API keys.

Next Steps

• Managing Fee Configurations — API endpoints for creating, viewing, scheduling, and retiring configurations
• Fee Calculation & Examples — The fee formula, interactive calculator, and detailed scenario walkthroughs