Fees and splits
How a fee rule decides what each parent takes, who bears it, and how the legs of a payment add up.
A fee rule on organization X is what X's parent takes from money flowing through X. The parent's admin sets it, because it is the parent's revenue.
await authClient.nuvion.feeRule({
organizationId: merchant.id, // the child; its parent is the beneficiary
bps: 300, // 3% (basis points, 100 = 1%)
flatMinor: 0, // plus a flat amount in minor units (pence)
minMinor: 50, // never less than 50
capMinor: 5000, // never more than 5000
bearer: "merchant", // "merchant" (deducted) or "payer" (added to the charge)
});The fee is:
fee = flatMinor + floor(amount × bps / 10000)
fee = clamp(fee, minMinor, capMinor), and never more than the amountEverything is an integer in the currency's minor unit, so there is no floating point.
The cascade
A payment flows child to parent. Each level keeps its inflow minus its fee and passes the fee up to the next level.
With a 3% rule on the merchant and a 50% rule on the reseller, a payment of 10000 gives:
| Organization | Receives | Why |
|---|---|---|
| Merchant | 9700 | 10000 minus the 3% fee (300) |
| Reseller | 150 | 300 minus the reseller's 50% (150) |
| Platform | 150 | the remainder |
The legs always sum to the amount charged. Fees round down, so any remainder moves up and ends at the platform. This is property-tested to sum exactly.
Who bears the fee
The bearer on the merchant's rule decides whether the fee is deducted or added:
merchant: the customer is charged the amount you asked for, and the merchant nets less.payer: the customer is charged the amount plus the fee, and the merchant nets exactly the amount you asked for.
Only the leaf rule's bearer is used. The quote tells you what the customer will be charged:
const { data } = await authClient.nuvion.payments({
organizationId: merchant.id,
amountMinor: 10_000,
currency: "GBP",
redirectUrl: "https://shop.example.com/done",
});
data.chargedMinor; // what the customer pays (base + fee when the payer bears it)
data.legs; // [{ organizationId, amountMinor }, ...] leaf first, platform lastNuvion charges its own fees too
Nuvion applies its own fee to inflows and to book transfers. The plugin does not attribute those to legs yet, so a very small payment can fail a leg with insufficient funds. See Failures and retries.
Rules are validated: bps is an integer from 0 to 10000, amounts are non-negative integers, and minMinor cannot exceed capMinor. A root organization has no parent, so it has no fee rule.