Billing

Customers → Billing is “subscriptions and the plans they are on. Each bill is a prompt to the customer’s phone, retried on your schedule.”

Needs billing.read to see and billing.write to change anything. Owner, admin, finance and developer can manage billing; member can view it. Without either you see “You do not have access to billing.”

Five tabs: Subscriptions, Plans, Invoices, Coupons and Retries.

Renewal is a prompt

On mobile money, each renewal is a payment prompt to the customer’s phone, which they approve. It is not taken silently, and if they ignore it nothing is collected — so do not tell your customers their subscription renews automatically. Where a customer pays with a card that can be charged again, the card is stored and charged at renewal without them; if it fails, the retries are prompts. The full picture is in Subscriptions.

Subscriptions

“Created by your server with POST /v1/subscriptions.” Filter by status.

Each row shows the customer and the product, the status, the price and period, the next date that matters — renews, trial ends, ends (cancelled for the end of the period) or ended — and how it is paid: the masked number prompts go to, or the stored card.

Status	Meaning
incomplete	The first bill is open and not yet paid.
trialing	In a free trial. Nothing collected yet.
active	Paid up for the current period.
past due	A bill failed. Retries continue on your schedule.
paused	Billing stopped. No bill opens.
cancelled	Ended — by you, by the customer, or because a bill went unpaid.

Action	What it does
Pause	Stops billing. No bill opens while it is paused. Not offered on an incomplete subscription.
Resume	Restarts billing. If the paid period ran out while it was paused, the next period starts now and is billed at once.
Discount	Applies a coupon, or removes the one it has — see Discounts on a subscription.
Cancel	Ends it now. “It ends immediately and any unpaid bill is voided.” The customer is emailed.

To let a customer keep what they have paid for, cancel at the end of the period instead. The portal cannot do that; your server can, with at_period_end — and so can the customer, from their subscription page.

Plans

“A plan’s price never changes once someone is on it. To change a price, create a new plan and retire the old one.”

New plan — “a price for something you sell, billed every period.”

Field	Notes
Product	An existing product, or A new product — then give the New product’s name.
Plan name	Optional: Monthly, Annual.
Price	In your settlement currency, per period.
Every / Interval	Every 1 month, every 3 months, every 1 year — days, weeks, months or years.
Free trial (days)	“Nothing is collected during a trial; the first bill follows it.”

Retire takes a plan off sale: nobody new can be subscribed to it, and existing subscribers keep renewing at their price. Put on sale reverses it.

Raising a price is always a new plan. Customers already on the old one keep the price they agreed to — move them by cancelling at period end and subscribing them to the new plan from your server.

Invoices

“Subscription bills, and one-off invoices you issue. Each attempt to collect is an ordinary payment in Transactions.”

Each row shows the invoice number, its amount and status, and either the period it bills or, for a one-off invoice, one-off with its due date and PO number. A discounted pill means a coupon took something off.

Status	Meaning
open	Not paid yet. Being collected.
paid	Paid — or a coupon, credit or credit note left nothing to pay.
void	Withdrawn: you voided it, or its subscription was cancelled while it was open.
uncollectible	Collection ran out unpaid.

Each attempt to collect is a normal payment. It appears in Transactions with the invoice number as its reference, settles into your balance like any other collection, and can be refunded like any other. An attempt refused before it reached a payment partner records why: “The payment was refused before it was sent: {reason}”, for example a limit, a blocked number, your account being suspended, or a method your account can’t use yet.

Viewing an invoice

View opens the invoice: its status, kind (Subscription, One-off or Proration), due date or period, and its lines — description, quantity, unit and amount. Below them are the totals:

Line	What it is
Subtotal	The lines added up.
Discount	Taken off by a coupon.
Credit	Paid from the customer’s credit, or taken off by a credit note while it was open.
Total	What the customer is asked to pay.
Credited back	Given back by credit notes after it was paid.

Any credit notes on it are listed underneath, followed by Customer credit — the customer’s balance in the invoice’s currency.

Give credit (needs billing.write) adds goodwill credit: “Goodwill or a correction. The customer’s next invoices in this currency spend it before anything is collected.” Enter an Amount and, optionally, a Note — “for your records.” Credit can only be added, never taken back, and it is never paid out as money.

A payment that arrives after its bill closed becomes credit. If a prompt expired, the bill was then paid another way (or voided, or written off), and the first payment turns out to have gone through after all, that amount is added to the customer’s credit as an overpayment: “Payment received after invoice INV-… was closed (paid).” You can leave it to pay their next bill, or refund the payment from Transactions. Refunding uses up that credit, so you can refund only the part that is still unspent; if the refund fails, the credit comes back. If the bill was still open, the late payment simply pays it.

New invoice

New invoice bills a customer you already have for something outside a subscription — consulting, a setup fee, an order. “A one-off bill to a customer you already have, collected by a prompt to their phone and retried on your schedule.”

Field	Notes
Find a customer / Customer	Search by part of a name, then choose. Phone numbers are shown masked.
Description, Qty, Unit (GHS)	One row per line. Add a line adds another, up to 50.
Network	Required. The mobile-money network of the number to prompt.
Number to prompt	“Defaults to the customer’s phone.”
Due in (days)	14 unless you change it, up to 90. “0 is due on receipt.”
Purchase order	Optional. “Printed on the invoice.”
Memo	Optional.

The total is shown as you type. When you issue it, the customer gets an SMS and an email at once, with the amount, invoice number, due date and PO number. Any credit they hold is spent on it first; if that covers it all, they are emailed a receipt instead and never prompted.

Through the portal’s API (POST /v1/billing/invoices), customer_id is optional. Send customer with phone (required), and optionally name and email, instead. The customer on file with that phone number is used, matched the same way payments match payers, or added if there isn’t one.

From the portal a one-off invoice is in GHS. Other currencies are issued from your server — see Invoices and credit.

How it is collected:

Due on receipt (0 days): the first prompt goes out within a minute.
On terms (1 day or more): nothing is asked for before the due date. The first prompt goes out at 09:00 on the due date, and the invoice tells the customer to expect it that day.
If a prompt fails, the customer is sent an SMS and email saying so, with the date it is still due by, and is prompted again on your Prompt on days — counted from the first prompt. When those days run out, nobody is prompted again, and the last message says so.
It stays open until 30 days after the due date, then becomes uncollectible. End the subscription on day does not apply to one-off invoices.
When they pay, they are emailed a receipt.

Void

Void is offered on an open one-off or proration invoice. “Collection stops and the customer is not prompted again. This cannot be undone.” Any of the customer’s credit the invoice had used goes back on their balance (“Credit returned: invoice … was voided.”), and the same happens when cancelling, pausing or closing voids a bill.

A subscription’s bill cannot be voided on its own. Pause or cancel the subscription instead, which voids its open bill. A paid invoice cannot be voided; issue a credit note. If the customer is being prompted at that moment, you are asked to try again in a few minutes.

Credit note

Credit note lowers what an invoice is worth. It is offered while there is something left to credit.

Field	Notes
Amount	Up to what is left: the amount due on an open invoice, or what has not been credited back on a paid one.
Reason	Order changed, Not satisfied, Duplicate, Fraudulent or Other.
Memo	Optional.

What it does depends on the invoice:

On an open invoice, the amount is taken off what is due. “Brought to zero, it is paid” — and a subscription waiting on its first bill becomes active.
On a paid invoice, the amount becomes credit for the customer. Their next invoices in that currency spend it, subscription bills included.

A customer’s credit balance, and Give credit, are on any of their invoices — see Viewing an invoice. The full history of a balance is in the API: Customer credit.

Coupons

“A percentage or an amount off a subscription’s bills. Customers enter a code when your server subscribes them; you can also apply one to a subscription here.”

Each coupon shows its name and code, what it takes off and for how long, how many times it has been used (out of its maximum), any deadline, and an inactive pill when it has been switched off.

New coupon:

Field	Notes
Name	“Shown on the invoice’s discount line.”
Code	“Optional. What a customer types. Leave empty for a coupon only you apply.” 3 to 40 letters, digits, dashes or underscores. Case does not matter.
Discount	Percentage, or Amount (GHS).
Percent off / GHS off	How much.
Applies to	The next bill, A number of bills (then Bills, 1 to 60) or Every bill.
Maximum uses	Optional. How many subscriptions can use it.

A coupon cannot be edited. Deactivate stops it being applied to anything new. Subscriptions that already have it keep it. Activate turns it back on.

A deadline for redeeming a coupon, or a restriction to particular products, can be set only from your server — see Coupons and discounts.

Discounts on a subscription

Discount on a subscription row: “Replaces any discount the subscription has. A bill already open keeps its amount.”

Apply puts the chosen coupon on the subscription. Only active coupons are listed. It comes off from the next bill.
Remove discount takes it off. Bills already opened keep their discount.

A subscription has one discount at a time. A percentage is rounded down to the pesewa, and a fixed amount never takes off more than the bill. When a coupon for a number of bills is used up, the subscription is billed at full price again.

Retries

“When a bill is not paid, we prompt again on these days after it opens, then end the subscription. Customers are told before each renewal.”

Field	Default	Notes
Prompt on days	0, 1, 3, 5	Counted from the day the bill opens, which is day 0.
End the subscription on day	7	If the bill is still unpaid, it becomes uncollectible and the subscription ends.
Renewal notice, days before	3	For monthly and longer plans, and before a trial ends.

When a change takes effect depends on the field:

Prompt on days applies at once — including to the next retry of a bill that is already open. Days are always counted from the day that bill opened.
End the subscription on day is fixed when a bill opens, so a bill already open keeps the pay-by date its customer was given. The new value applies to bills opened from now on.
Renewal notice, days before applies from the next notice.

More prompts are not always better: a customer who has decided not to renew and is prompted every day is more likely to complain than to pay.

What your customers receive

PaySigna sends these on your behalf, with your business named in them:

When	How
They subscribe — with their manage code	Email
Before each renewal, and before a trial ends	SMS and email
A bill is due, with the first prompt	SMS and email
A payment failed, with the date to pay by	SMS and email
A bill was paid — a receipt	Email
The subscription ended	Email
You issued them a one-off invoice	SMS and email
A prompt for a one-off invoice failed, with the date to pay by	SMS and email
They paid a one-off invoice, or credit covered it — a receipt	Email

The bill-due message is not sent when a stored card is being charged, since nothing is asked of the customer.

Your customers’ subscription page

Every notice carries the customer’s manage code. At app.paysigna.com/subscription they enter it — “Enter the manage code from your latest email or SMS from PaySigna” — and see the subscription: its status, price, and the number prompts go to. From there they can:

Pay now — sends a fresh prompt for a bill that is open, so a customer who missed a prompt does not have to wait for the next retry;
Cancel — at the end of the period they have paid for. If nothing has been paid yet, it ends at once.

No sign-in is needed and the code is never put in a link; the customer types it. Tell your customers this page exists. Cancelling must be as easy as subscribing is the single biggest reducer of recurring-payment disputes, and it is far cheaper than a chargeback.

When a customer cancels there, the subscription shows the customer as the reason, and your server receives subscription.cancel_scheduled or subscription.canceled.