Configure Payment Fee Formulas – BriteCore Support

Define the formula used to calculate the processing fee for credit card, debit card, and Automated Clearing House (ACH) payments.

Introduction

A payment fee formula is an expression that is evaluated to calculate the processing fee applied to a payment. Configure a separate formula for each payment method within Settings > Payments > Payment Fees for every scope (Global or State) defined. Create a separate formula for each payment method to support your organization's pricing and payment processing requirements. This article explains the supported formula syntax, the safeguards that apply during evaluation, and common formula examples. For an introduction to all Payments settings, see Payments Settings Overview.

How Fee Formulas Work

A formula is a single expression that evaluates to a dollar amount. It has access to one variable, two optional functions, and standard arithmetic and comparison operators.

Each time a credit card, debit card, or ACH payment is processed, the formula is evaluated with amount set to the payment amount. The result is rounded to the nearest cent and added to the payment.

Two safeguards apply automatically:

Negative results are rejected: If a formula evaluates below zero, the transaction is blocked and an error is recorded. Design formulas so they cannot return a negative amount.
Invalid formulas fall back to 0: If the formula cannot be evaluated, no fee is charged and a notification is sent to Settings > System Wide > Administrative Alerts > Payments. The notification includes the formula, the payment amount, and the error.

Before You Begin

Confirm the following before you start:

Payment Processor integration: Install and configure the Stripe Payment Processor integration under Settings > Vendor Integrations. Without this integration, payment fee formulas are not applied during payment processing.
Administrator access: You must have administrator privileges to access and manage settings under Settings > Payments.

Write a Formula

Go to Settings > Payments > Payment Fees and select the scope you want to edit.
In the Formula field for a payment method, enter the expression directly, without quotation marks and with up to 100 characters.
Select Save changes.

To change the text shown next to a payment method, edit its description under Messaging on the same page. Keep each description in sync with its formula.

Write percentages as decimals: use 0.05 for 5 percent, not 5%. Whitespace inside a formula is ignored, so you can space out longer expressions for readability.

Test a Formula

After saving changes, enter a value in the Test amount field to preview the calculated fee for each method.
Place a test payment for the payment method in a non-production environment.
Confirm the fee on the receipt matches what you expect.

Note: If the fee shows as 0 when it should not, check Settings > System Wide > Administrative Alerts > Payments for a notification describing the error.

Reference

Use these tables to look up the variable, functions, operators, and examples that formulas support.

Variable

Payment fee formulas support a single variable: the payment amount. No other values or attributes are available for use in the formula.

Variable	Meaning
`amount`	The payment amount being charged, as a decimal (for example, `100.00`).

Functions

Two functions are available. Helpers such as round, abs, and int are not callable and are not needed, because results are rounded to the nearest cent automatically.

Function	Meaning
`min(a, b, ...)`	Returns the smallest of the arguments.
`max(a, b, ...)`	Returns the largest of the arguments.

Arithmetic operators

Operator	Meaning	Example
`+`	Add.	`amount * 0.025 + 0.30`
`-`	Subtract.	`amount * 0.05 - 1`
`*`	Multiply.	`amount * 0.05`
`/`	Divide.	`amount / 100`
`**`	Power.	`2 ** 3` returns `8`
`//`	Floor divide, then round down to a whole number.	`250 // 100` returns `2`
`%`	Modulo, the remainder after dividing.	`250 % 100` returns `50`

Comparison operators

Comparison operators produce a true or false result. Use them inside the conditional form to choose between two values.

Operator	Meaning	Example
`<`	Less than.	`amount < 20`
`<=`	Less than or equal to.	`amount <= 100`
`>`	Greater than.	`amount > 50`
`>=`	Greater than or equal to.	`amount >= 100`
`==`	Equal to, written with two equals signs.	`amount == 100`
`!=`	Not equal.	`amount != 0`

Conditional form

Choose between two values inline. Do not use an if statement.

value_if_true if condition else value_if_false

For example:

1 if amount < 20 else amount * 0.05

Example formulas

What you want	Formula
No fee	`0`
Flat $1.00 fee on every payment	`1.00`
Flat 5% of the payment amount	`amount * 0.05`
2% of the amount, but at least $0.50	`max(amount * 0.02, 0.50)`
2% of the amount, capped at $10	`min(amount * 0.02, 10)`
2% with a $0.50 floor and a $10 ceiling	`max(min(amount * 0.02, 10), 0.50)`
$1 flat below $20, then 5% above	`1 if amount < 20 else amount * 0.05`
3% under $100, otherwise 2%	`amount * 0.03 if amount < 100 else amount * 0.02`
2.5% plus a $0.30 fixed amount	`amount * 0.025 + 0.30`

Common mistakes

Using a variable that does not exist: Only amount is recognized. Names such as payment_amount, premium, or total fall back to 0.
Calling an unsupported function: Only min and max are available.
Using an if statement: Write the condition inline, as in 1 if amount < 20 else amount * 0.05.
Forgetting parentheses around min or max arguments: Wrap the arguments, as in min(amount * 0.02, 10).
Writing a percentage with a % sign: Use the decimal form, such as 0.05 for 5 percent.
Wrapping the formula in quotes: Enter the expression directly, as in amount * 0.05.