Fees and billing

Billium charges a platform fee on every payment it settles. Because Billium is non-custodial, the platform fee is never deducted from the on-chain transfer — the customer's payment arrives at your wallet in full. Fees are accumulated in a separate MonthlyBill ledger and charged to you at the end of each month.

Platform fees by tier

Every merchant belongs to one of three pricing tiers. The tier determines the percentage Billium takes from each settled payment:

The fee percentage is resolved from the merchant's pricingTier field at the moment a payment is calculated — not baked into the invoice at creation time. That means if you upgrade from BASE to GROWTH mid-month, invoices created before the upgrade will still settle at the new rate when they're paid.

How the platform fee is calculated

platformFeeUsd = invoice.rawAmount × merchant.feePercentage

For a $100 invoice on a BASE merchant, the platform fee is $1.00. That $1.00 is recorded on Payment.platformFee and added to the merchant's current MonthlyBill.totalAmountUsd when payment.paid fires.

Two things this is not:

1. It is not deducted from the on-chain amount. The customer pays $100 worth of crypto, all of which arrives at your wallet. Billium invoices you separately for the $1.00 fee at the end of the month.
2. It is not charged per invoice. Fees aggregate across all your settled payments for the current UTC calendar month and become one bill.

Customer-paid fees (optional)

You can choose to pass the fee on to the customer instead of absorbing it yourself. Three fields on the merchant's Checkout configuration control this:

With coverProcessingFees = false, the customer sees an endAmount that's higher than the rawAmount:

endAmount = rawAmount × (1 + customFeePercentage) + fixedFeeIfOverThreshold

A $100 invoice with a 2% customer fee becomes a $102 checkout. The extra $2 goes into the same settled payment and is recorded alongside the base amount.

Monthly billing

Platform fees don't hit your books one at a time — they aggregate into a single bill per calendar month. Here's how it works.

Aggregation on every paid payment

When payment.paid fires, a listener runs in the same transaction that settled the payment:

1. Look up (or upsert) the MonthlyBill for (merchantId, billingPeriod = start of current UTC month).
2. Idempotency check: if payment.monthlyBillId is already set, skip — this payment was already billed.
3. Increment MonthlyBill.totalAmountUsd by the platform fee in USD.
4. Link Payment.monthlyBillId to the bill.

If the current month's bill has already been paid (rare, but possible if a merchant pays their bill mid-month and a new payment comes in), the fee rolls forward to next month's bill instead of re-opening the closed one.

Monthly finalization

On the 1st of every month at 00:00 UTC, Billium finalizes the previous month's bills. Bills already marked PAID are left alone — you'll never be charged twice for the same period.

Overdue bills

PENDING bills older than 30 days are automatically marked OVERDUE and you'll get an email notification so you know to act on it. Persistently overdue bills can lead to account suspension — contact support if you need a payment plan.

Paying your bill

Bills can be paid two ways:

• Stripe (card / ACH / SEPA, depending on your region). POST /api/v1/billing/stripe/pay-bill creates a Stripe PaymentIntent keyed by a deterministic idempotency hash, and the bill flips to PAID when Stripe's payment_intent.succeeded webhook lands.
• Crypto — Billium creates an internal invoice linked to the bill via metadata.monthlyBillId, and the bill flips to PAID when that invoice reaches PAID status. A slightly recursive setup, but entirely consistent with how every other payment works.

Both flows are idempotent: hitting the pay-bill endpoint twice for the same bill is safe and will not double-charge you.

What a merchant's invoice looks like

For completeness, here's what a paid $100 invoice on a BASE-tier merchant with coverProcessingFees = true produces:

You can always pull your current month's fee accumulation from the reports API in the dashboard — see the Reports section of your merchant settings.