Tenant Billing & Stripe

Two flows of money — a recap

There are two billing flows on this platform. Don't confuse them.

Flow	Who pays whom	Where it's configured
Platform billing	You pay us	Settings → Billing → Subscription tab + Payment Methods tab
Tenant billing	Your tenants pay you	Settings → Billing → Tenant Billing tab + Settings → Billing Config

This chapter is about the second one. How you charge your tenants.

The three Stripe modes — deep dive

Mode	Where charges land	Setup time	When to use
Platform	Our Stripe account	None	Default. Use while waiting for Connect or for testing.
Connect (Express)	Your Stripe account, via Stripe-hosted onboarding	~5 minutes	Recommended. 95% of partners.
Custom Keys	Your existing Stripe account, via API key	Few minutes	Only if you have an existing Stripe setup with subscriptions, custom products, or webhooks you don't want to disturb.

Platform mode

You don't do anything. Tenants pay our Stripe account. Each month we manually transfer your earnings (minus our 3.99% fee) to a bank account you provide via support ticket. Settlement is monthly, around the 15th.

Use this temporarily. It's slow and manual. There's no good reason to stay here long-term.

Connect (Express)

Stripe creates a separate "Connected Account" for you. Customers' charges hit your account directly. We attach an application_fee of 3.99% of each charge that gets routed to us. You see the rest in your Stripe dashboard immediately.

Setup walkthrough is in chapter 5. Once active:

• Charges land in your Stripe within 7 days (Stripe's standard payout schedule, configurable)
• Refunds work normally — initiate from the platform or from your Stripe dashboard
• Disputes land in your Stripe — you handle them
• Tax forms (1099-K) are issued by Stripe to you, not by us

Custom Keys

You provide your own Stripe sk_live_... secret key. We make API calls as you. Charges look identical to anything else you do in your Stripe account.

Setup: Tenant Billing tab → Show Advanced Options → Custom Stripe Keys → enter secret key + publishable key → Save.

Your secret key is encrypted at rest with AES-256-GCM before storage. Only the resolved processor reads it.

Use Custom Keys if:

• You already have a complex Stripe Products/Prices/Subscriptions catalog you don't want to recreate
• You have your own webhooks you've already wired up to your CRM
• You want zero application fee (you don't pay us 3.99% on tenant charges in custom mode — but our platform subscription fee is higher to compensate)

Don't use Custom Keys if you just want simpler accounting. Connect is simpler in every way except this one specific case.

Statement descriptor

The text that shows up on your customer's credit card statement. Set this.

Settings → Billing → Tenant Billing tab → Statement Descriptor field. Max 22 characters. No special punctuation other than spaces, dashes, and &.

Examples that work:

• ACME PHONES
• HRC TELECOM
• PINEDALE VOIP

Examples that don't:

• Acme's Phone Co. (apostrophe + period)
• THIS IS A REALLY LONG NAME (over 22 chars)

If a customer doesn't recognize the charge on their statement, they file a chargeback. Chargebacks cost $15-25 each, count against your Stripe risk profile, and can get your account flagged. Your customers should recognize the charge at a glance. Use a name you actually market under.

Billing profiles

A billing profile is a template for how you charge a tenant. Settings → Billing → Billing Config (or via the Settings menu, "Billing Config" item).

Every tenant gets assigned one billing profile when you create them. The profile defines:

• Pricing model — Pay-As-You-Go or Flat Rate
• Monthly base fee — for Flat Rate models
• Included quantities — extensions, DIDs, minutes per month
• Overage rates — what you charge above the included amounts
• Per-unit rates — for PAYG: what you charge per extension/DID/minute

You can create as many profiles as you like. Common patterns:

• Free Trial — $0/mo, 30-day expiration, then auto-converts to Paid Starter
• Small Office — $99/mo flat, 5 extensions + 1 DID + 500 minutes included
• Growing Business — $249/mo flat, 25 extensions + 5 DIDs + 2500 minutes
• Enterprise — PAYG with $5/extension and $0.018/minute, no monthly minimum

Defaults: Pay-As-You-Go and Flat Rate Starter profiles are created automatically when you sign up. Edit them or create new ones.

The fields you set on a billing profile

When you open the profile editor (Settings → Billing Config → New / Edit), you'll see these rate fields:

• Monthly base fee — what the tenant pays just for having an account
• Extension /mo — per-extension rate
• Standard DID /mo — monthly rate for local numbers
• Toll-Free DID /mo — monthly rate for toll-free numbers (set this higher; your platform cost on toll-free DIDs is higher too)
• Per Minute — your usage rate

A note on the per-minute field: the profile editor exposes a single per-minute rate that applies to all outbound traffic for tenants on this profile. Under the hood, the platform meters local and toll-free traffic separately — your underlying platform cost differs by call type (see Account & Subscription for the breakdown). The rate you set here is what your tenant sees on their invoice for every billable minute, regardless of call type.

If you want to charge your tenants differently for local vs. toll-free, the simplest pattern today is to create two billing profiles (e.g. "Local-Only" and "Mixed Traffic") and assign tenants based on their expected usage. Per-call-type tenant rates are on the roadmap.

Switching a tenant to a different profile

In the tenant edit modal, change Billing Profile. The change applies at the start of the next billing cycle. Don't switch mid-cycle if you can avoid it — it makes the prorated math messy.

Tax jurisdictions

If you collect sales tax / VAT / GST on phone services, configure jurisdictions here.

Settings → Billing → Tax Jurisdictions. Click Add Jurisdiction:

• Name — display label (shown on invoice line)
• Jurisdiction code — e.g., US-AR-Pulaski or CA-ON
• Tax rate — decimal (e.g., 0.085 for 8.5%)
• Enabled — toggle on/off

When you enable a jurisdiction, all new invoices to tenants in that jurisdiction include the tax line. Existing invoices are unchanged.

Tax rules vary wildly by jurisdiction. Talk to a CPA before configuring this. Some jurisdictions tax voice services as a utility (different rate), some apply gross receipts tax, some don't tax intrastate but do tax interstate. The platform applies the rate you set; the legal compliance is on you.

Tenant invoices

Settings → Billing → Tenant Invoices (or top nav: Reports → Tenant Invoices). Lists every invoice generated for any of your tenants.

Columns:

• Invoice number
• Tenant name
• Issue date
• Due date
• Status (Draft / Sent / Paid / Overdue / Cancelled)
• Amount
• Actions

Click any row to see line items. Each invoice shows:

• The tenant being billed
• The billing period
• Each line item (extensions, DIDs, per-minute usage, additional charges)
• Subtotal, tax, total
• Payment status

Stats cards at the top: total invoices, paid count, unpaid count, outstanding amount.

Invoices are generated automatically:

• Anniversary cycle — for Flat Rate tenants, on the same day each month (the day they activated)
• End of month — for PAYG tenants, on the 1st with usage from the prior month

You can manually generate an invoice via the API or open a support ticket if you need an off-cycle invoice.

Refunds and disputes

Initiating a refund

Find the invoice. Click Refund. Enter the amount (full or partial). Confirm. The refund is sent to the customer's card via Stripe (3-5 business days for the customer to see it).

The wallet credit (for usage that was refunded) is automatically restored to your tenant's balance, so you don't double-pay them.

Handling a dispute

Disputes (chargebacks) land in your Stripe dashboard if you're on Connect or Custom Keys. We don't intermediate.

When you get one, gather evidence (the invoice, the tenant agreement, call records showing the service was rendered) and submit through Stripe's dispute interface. Most service-not-rendered disputes are winnable if you can show the calls happened.

If you're on Platform mode, we forward dispute notifications to your billing email. Reply with evidence and we'll submit on your behalf.

Auto-suspend on non-payment

By default, tenants who don't pay their invoices are flagged at 7 days overdue and auto-suspended at 14 days. Suspended tenants can't take calls.

Adjust the timing per-tenant (in their billing profile) or globally (Settings → Billing Config → Default Suspension After).

Some partners prefer manual suspension (review every overdue case yourself); some prefer aggressive auto-suspension. Choose based on your customer base.