Fee Configuration

Configure fees charged to merchants for payment processing. The fee model defines how revenue is split between you, the platform, payment providers, and referral partners.

Fee Decomposition Model

Every transaction fee is broken down into four configurable components and one derived component:

merchantFee = providerFee + platformFee + tenantFee + partnerCommission

The formula for your margin:

tenantFee = merchantFee - providerFee - platformFee - partnerCommission

Fee Visibility by Role

Not all users see the same fee information. Visibility is determined by role:

Fee Schedules

A fee schedule is a rate card — a named collection of fee rules that define pricing for specific transaction types and currencies.

Fee Schedule Lifecycle

Fee schedules follow a strict lifecycle to ensure pricing integrity:

draft  →  active  →  archived

To change pricing on an active schedule: create a new schedule (draft), configure the updated rules, activate it, then reassign your entities to the new schedule. The old schedule can be archived once all assignments have transitioned.

Creating a Fee Schedule

Portal: Navigate to Fees > Fee Schedules > Create.

1. Name: Give the schedule a descriptive name (e.g., "Standard Card Rates EUR").
2. Fee rules: Add one or more rules. Each rule defines pricing for a specific combination:

All monetary values are in integer minor units (cents, pence, etc.). For example, EUR 0.30 is represented as 30.

Fee Rule Matching

When a transaction is processed, the billing engine selects the appropriate fee rule from each applicable schedule by matching on three keys:

1. Transaction type — payment, refund, chargeback, etc.
2. Transaction outcome — successful, declined, or any
3. Currency — must match the transaction currency exactly

Within a single fee schedule, no two rules may share the same (transactionType, transactionOutcome, currency) combination. The system rejects duplicates at creation time.

Fee Assignment Cascade

Fee schedules are assigned at multiple levels. The assignment level determines which fee component is being configured, and cascade resolution determines which assignment wins when multiple levels are configured.

Assignment Levels

Level 1: Terminal                              → Provider cost schedule    (what the acquirer charges you)
Level 2: Channel (per currency + method)       → Merchant fee schedule    (overrides merchant-level)
         Merchant (per currency + method)      → Merchant fee schedule    (what you charge the merchant)
Level 3: Tenant                                → Default merchant fee     (fallback for merchants without direct assignment)
Level 4: Platform                              → Platform fee schedule    (Miracle software fee)
Level 5: Partner (via PartnerAssignment)       → Partner commission schedule (referral partner share)

How Assignment Resolution Works

When calculating fees for a transaction, the system resolves each component independently:

1. Provider cost — Always from the terminal's assigned schedule (Level 1). Required.

2. Merchant fee — Resolved using a nearest-wins cascade. The system checks in this order and uses the first match found:

Channel-level overrides merchant-level. If a channel has its own fee schedule for (EUR, card), that takes priority over any merchant-level assignment for the same combination. Tenant-level is a fallback — it provides default merchantFee pricing when no direct merchant or channel assignment exists.

3. Platform fee — From the platform-level schedule (Level 4). Optional — if not configured, platformFee = 0.

4. Partner commission — From the partner assignment (Level 5). Optional — if no partner is linked, partnerCommission = 0.

Assigning a Fee Schedule

Portal: Select the target entity (merchant, terminal, etc.), then go to the Fees tab and select Assign Schedule.

For merchant-level and channel-level assignments, you specify both the currency and payment method. This allows different rates for different combinations — for example, 2.9% for card payments in EUR but 1.5% for bank transfers in EUR.

Common Pricing Models

Here are practical examples of how to configure typical fee structures:

Fixed fee

Charge a fixed amount per transaction regardless of size.

Percentage fee

Charge a percentage of the transaction amount.

Fixed plus percentage fee

Charge both a percentage and a fixed fee per transaction.

For a EUR 100.00 transaction (10000 minor units), the merchant fee would be: 290 bps of 10000 + 30 = 290 + 30 = 320 minor units (EUR 3.20).

Fee with floor and ceiling

Charge a percentage with both minimum and maximum bounds.

For a EUR 10.00 transaction, the raw fee would be 20 cents — but the minimum floor of EUR 0.50 applies. For a EUR 5,000.00 transaction, the raw fee would be EUR 100.00 — but the maximum ceiling of EUR 50.00 caps it.

Recurrent Fees

In addition to per-transaction fees, the system supports periodic (recurrent) fees that are not tied to individual transactions. These cover recurring charges like access fees, monthly minimums, or subscription costs.

Two Directions

Recurrent fees operate in two directions:

How Recurrent Fees Work

Recurrent fees use a three-part model:

1. Template — Defines the fee: name, amount, interval, and direction. Created by the entity that charges (platform creates templates for tenants, you create templates for your merchants).
2. Assignment — Links a template to a specific target entity (tenant or merchant) with an effective date. Assignments can be active, suspended, or canceled.
3. Charge — An immutable execution record created each billing period. Linked to a ledger entry for audit trail.

Intervals

The per_settlement interval is useful for charges like statement fees or settlement processing fees.

Managing Recurrent Fee Templates

Portal: Navigate to Fees > Recurrent Fee Templates.

• Create a template with a name, amount, interval, and direction.
• Once a template has active assignments, its amount and interval become immutable. To change terms, create a new template and reassign.
• Deactivate a template to prevent new assignments (existing assignments continue until canceled).

Managing Recurrent Fee Assignments

Portal: Select a merchant, go to the Fees tab, then Recurrent Fees.

• Assign a template with an effective start date.
• Suspend an assignment to temporarily pause charging.
• Cancel an assignment to stop it permanently.

Fee History

Fee schedules maintain a full history. When you update a fee assignment:

• A new record is created with an effectiveFrom date.
• The previous record automatically receives an effectiveTo date.
• Historical records are never deleted or modified.

This means the system can explain which fees were in effect for any transaction at any point in time — useful for auditing and dispute resolution.

Best Practices

• Review tenantFee after configuration to verify your margin is positive across all transaction types and currencies.
• When onboarding a new provider, create a provider cost schedule that matches the acquirer's actual rate card.
• Use fixed_plus_percentage pricing for card payments to cover both the interchange percentage and the per-transaction network fee.
• Use maxAmount (ceiling) to cap fees on high-value transactions where a flat cap is more competitive.
• For recurrent fees, start with monthly interval — it is the most common billing cycle for merchant access fees.