> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyberpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing Setup

> Configure invoicing, payment terms, tax, billing cycles, settlement destination, and platform fees.

<a
  href="https://fyberpay.com/embed/docs-chat"
  target="_blank"
  rel="noopener noreferrer"
  aria-label="Ask FyberPay docs chat"
  style={{
position: 'fixed',
bottom: '24px',
right: '24px',
width: '56px',
height: '56px',
borderRadius: '9999px',
background: 'linear-gradient(135deg, #6366f1 0%, #7c3aed 100%)',
boxShadow: '0 4px 16px rgba(99, 102, 241, 0.35)',
color: 'white',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
zIndex: 9999,
textDecoration: 'none',
transition: 'transform 150ms ease',
}}
>
  <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
    <path d="M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8v.5z" />
  </svg>
</a>

## Overview

FyberPay handles the entire billing lifecycle for your ISP: invoice generation, tax calculation, payment tracking, and receipt delivery. This guide walks you through configuring billing to match your business requirements.

## Two sides of "billing"

Settings → Billing covers two things that are easy to confuse:

1. **How you bill your subscribers** – plans, invoice prefix, currency, tax, grace period, dunning. This is the bulk of this page.
2. **How FyberPay bills you (and pays you)** – your platform fee, hotspot commission accrual, and the **Settlement** section (destination, batch or instant mode, payout threshold) that governs how centralized collections reach you.

Subscriber-side billing details are below. Platform-side billing has its own section: see [Platform fees and settlement](#platform-fees-and-settlement).

## Billing Settings

Navigate to **Settings > Billing** to configure your organization's billing defaults.

### Invoice Configuration

<Steps>
  <Step title="Set your invoice prefix">
    Choose a prefix for your invoice numbers (e.g., `ACM` produces invoice numbers like `ACM-0001`, `ACM-0002`). This prefix is applied to all auto-generated and manual invoices.
  </Step>

  <Step title="Configure your currency">
    FyberPay defaults to **KES** (Kenyan Shilling). The currency code appears on all invoices, receipts, and the subscriber portal.
  </Step>

  <Step title="Set the grace period">
    The grace period defines how many days after the due date an invoice is considered overdue. The default is **3 days**. After this period, the dunning pipeline begins.
  </Step>

  <Step title="Add payment details">
    Enter your **M-Pesa Paybill number**, bank name, and account details. These appear on invoice PDFs so subscribers know where to send payments.
  </Step>

  <Step title="Customize the invoice footer">
    Add a custom footer message to all invoices, such as your terms of service or a thank-you note.
  </Step>
</Steps>

### Tax Settings

<Info>
  FyberPay calculates tax as a percentage of the subtotal. For VAT-registered ISPs in Kenya, set the tax rate to **0.16** (16% VAT). Non-VAT-registered ISPs should leave it at **0** (the default).
</Info>

Navigate to **Settings > Billing** and set the **Tax Rate** field. The rate is expressed as a decimal:

| Scenario         | Tax Rate Value |
| ---------------- | -------------- |
| No VAT (default) | `0`            |
| Kenya VAT (16%)  | `0.16`         |
| Custom rate      | `0.xx`         |

Tax is calculated automatically on every invoice. Given a plan priced at KES 2,500 with a 16% tax rate:

* Subtotal: KES 2,500
* Tax (16%): KES 400
* Total: KES 2,900

### Receipt Templates

Invoice PDFs are generated automatically and include:

* Your organization name, logo, and contact details (from **Settings > Organization**)
* Subscriber name and phone number
* Plan name, billing period, and line-item breakdown
* Tax breakdown (subtotal, tax amount, total)
* Payment instructions (M-Pesa Paybill, bank details)
* Custom footer text

<Tip>
  Upload your company logo at **Settings > Organization > Logo** to brand your invoices. The logo appears in the top-left corner of all generated PDFs.
</Tip>

## Billing Cycles

Each subscription plan defines its own billing cycle in days. When you create a plan at **Billing > Plans**, you set the `billingCycleDays` field.

### Common Billing Cycles

| Cycle       | Days | Typical Use                  |
| ----------- | ---- | ---------------------------- |
| Monthly     | 30   | Standard residential plans   |
| Quarterly   | 90   | Discounted long-term plans   |
| Semi-annual | 180  | Business or enterprise plans |
| Annual      | 365  | Large-volume corporate deals |

<Info>
  Billing cycle days are counted from the subscription activation date. A 30-day cycle activated on March 1st expires on March 31st.
</Info>

### How Billing Cycles Work

1. A subscriber activates a plan with a 30-day cycle
2. FyberPay sets the expiry date to 30 days from activation
3. **Three days before expiry**, FyberPay auto-generates a renewal invoice
4. The invoice is sent to the subscriber via SMS and email
5. On payment, the subscription extends by another 30 days
6. If unpaid, the dunning pipeline kicks in after the grace period

## Auto-Generated Invoices

FyberPay runs a bulk invoice generation job that creates invoices for all subscriptions expiring within the next 3 days. This process:

* Skips subscriptions that already have a pending (draft or sent) invoice
* Calculates tax based on your org's configured tax rate
* Fires an `invoice.created` event that triggers SMS/email notifications and Bill Manager sync

### Invoice Status Lifecycle

Invoices move through these statuses:

```
draft -> sent -> paid
                  \-> overdue -> paid
                              \-> void
```

| Status      | Meaning                                                 |
| ----------- | ------------------------------------------------------- |
| **Draft**   | Invoice created but not yet delivered to subscriber     |
| **Sent**    | Invoice delivered via SMS, email, or Bill Manager       |
| **Overdue** | Past the due date and grace period, unpaid              |
| **Paid**    | Payment received and matched                            |
| **Void**    | Cancelled with a reason (does not count toward revenue) |

### Manual Invoice Actions

From the **Billing > Invoices** page, you can:

* **Send** a draft invoice (transitions to "sent" status)
* **Void** an invoice with a reason (available for draft, sent, or overdue invoices)
* **Create a credit note** for a paid invoice (partial or full refund, creates a negative-amount invoice)

## Prorated Charges

When a subscriber upgrades or downgrades their plan mid-cycle, FyberPay calculates prorated charges automatically.

<AccordionGroup>
  <Accordion title="How proration works">
    FyberPay calculates the daily rate of both the old and new plans, then computes the difference for the remaining days in the current billing cycle.

    **Example**: A subscriber on the KES 2,000/month plan (30 days) upgrades to the KES 3,000/month plan with 15 days remaining.

    * Old daily rate: KES 2,000 / 30 = KES 66.67
    * New daily rate: KES 3,000 / 30 = KES 100.00
    * Difference per day: KES 33.33
    * Proration amount: KES 33.33 x 15 = **KES 500**

    The subscriber is charged KES 500 for the upgrade.
  </Accordion>

  <Accordion title="Downgrades">
    When a subscriber downgrades, the proration calculation produces a credit. This credit is applied to their next invoice automatically.
  </Accordion>

  <Accordion title="Mid-cycle plan changes and RADIUS">
    Plan changes take effect immediately. FyberPay updates the subscriber's RADIUS group in real-time, so bandwidth limits change within seconds of the plan change being confirmed.
  </Accordion>
</AccordionGroup>

## Billing Notifications

FyberPay sends automated billing notifications at several points:

| Trigger                         | Channel     | Content                                   |
| ------------------------------- | ----------- | ----------------------------------------- |
| Invoice created                 | SMS + Email | Invoice details with payment instructions |
| Payment received                | SMS + Email | Payment confirmation receipt              |
| Expiry reminder (3 days before) | SMS + Email | Renewal reminder with pay link            |
| Expiry reminder (1 day before)  | SMS + Email | Urgent renewal reminder                   |
| Expiry day                      | SMS + Email | Final reminder before service restriction |

<Tip>
  Configure reminder timing at **Settings > Notifications**. The default sends reminders at 3 days, 1 day, and 0 days before expiry. You can adjust these intervals to match your subscriber base.
</Tip>

Notification channels can be toggled independently. Navigate to **Settings > Notifications** to enable or disable SMS and email notifications.

## Platform fees and settlement

The lines below describe how money flows **between FyberPay and your ISP** (not between you and your subscribers).

### Monthly platform fee

A flat monthly fee tied to your tier (Starter / Growth / Pro / Enterprise) plus a small per-active-subscriber charge. Exact numbers live at [`/pricing`](https://fyberpay.com/pricing) and on your **My Billing** page in the admin. Charged on the same day every month, on a platform invoice that you can settle via M-Pesa or bank transfer.

### Transaction fee (centralized paybill)

FyberPay charges **no transaction fee** on subscriber payments collected into the shared M-Pesa Paybill (`4026145`). Collections settle to you in full; the only deduction is the actual **M-Pesa B2B fee** on each payout (a Safaricom charge, itemised on every disbursement and borne by the ISP). FyberPay's revenue is the monthly platform invoice, not a cut of your collections.

ISPs running their own Daraja credentials in **direct mode** collect straight into their own paybill, so neither the settlement step nor the payout fee exists there. See [M-Pesa Integration → Centralized vs Direct](/guides/mpesa-integration) for the choice between modes.

### Hotspot commission

A percentage of hotspot voucher revenue, **accrued per voucher purchase and billed monthly** on the platform invoice — not deducted at payment time. The rate is configured per-org; see your **My Billing** page for the current rate.

### Settlement destination

Centralized-mode payments collect into FyberPay's paybill, then disburse to the ISP per your **settlement mode**: batch (accumulate to a payout threshold, checked daily, one flat M-Pesa fee per payout) or instant (per payment), with a **Disburse now** button for on-demand sweeps. The destination and mode are configured at **Settings → Billing → Settlement**:

* **M-Pesa Paybill** – your Safaricom paybill plus an account name.
* **M-Pesa Till (Buy Goods)** – a till number (e.g. `5332138`). No account-number suffix.
* **Bank via Tuma** – Tuma-handled payout to a Kenyan bank account.

If no destination is configured, the platform admin sees the disbursement flagged with `MissingSettlementPaybill` on the disbursements dashboard, and funds stay parked until you fix it.

## Next Steps

<CardGroup cols={2}>
  <Card title="M-Pesa Integration" icon="mobile-screen" href="/guides/mpesa-integration">
    Set up STK Push, Bill Manager, and payment reconciliation.
  </Card>

  <Card title="Dunning Automation" icon="bell" href="/guides/dunning-automation">
    Configure automated payment retries, walled garden, and suspension rules.
  </Card>
</CardGroup>