Define the formula BriteCore uses to calculate the processing fee applied to credit card, debit card, and ACH payments. Create separate formulas for each payment method to support your organization's pricing and payment processing requirements.
Introduction
A payment fee formula is an expression that BriteCore evaluates to calculate the processing fee applied to a payment. Configure a separate formula for each payment method within Settings > Payments for every scope (Global or State) defined. This article explains the supported formula syntax, the safeguards BriteCore applies during evaluation, and common formula examples.
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 BriteCore processes a credit card, debit card, or ACH payment, it evaluates the formula with amount set to the payment amount, rounds the result to the nearest cent, and adds that amount to the payment.
Two safeguards apply automatically:
- Negative results are rejected. If a formula evaluates below zero, BriteCore blocks the transaction and records an error. Design formulas so they cannot return a negative amount.
- Invalid formulas fall back to 0. If BriteCore cannot evaluate the formula, it charges no fee and sends a notification to Settings > System Wide > Administrative Alerts > Payments. The notification includes the formula, the payment amount, and the error.
Before You Begin
- Payment Processor integration: The Stripe Payment Processor integration must be installed and configured 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 and select the scope you want to edit.
- In the Formula field for a payment method, enter the expression. Enter it directly, without quotation marks.
- Update the matching Description field so the displayed text stays in sync with the formula.
- Select Save changes.
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
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 BriteCore rounds results 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 → 8 |
| // | Floor divide, then round down to a whole number. | 250 // 100 → 2 |
| % | Modulo, the remainder after dividing. | 250 % 100 → 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. Note the 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: 1 if amount < 20 else amount * 0.05.
- Forgetting parentheses around min or max arguments. Wrap the arguments: min(amount * 0.02, 10).
- Writing a percentage with a % sign. Use the decimal form: 0.05 for 5 percent.
- Wrapping the formula in quotes. Enter the expression directly: amount * 0.05.
See Also
- Configure Payment Processing Fees and Disclosures by State
- Set up the Payment Processor integration (Settings > Vendor Integrations)
- Administrative Alerts
