Skip to Content
better-auth-nuvion

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 amount

Everything 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:

OrganizationReceivesWhy
Merchant970010000 minus the 3% fee (300)
Reseller150300 minus the reseller's 50% (150)
Platform150the 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 last

Nuvion 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.

On this page