Bills and accounts

A bill is an amount a service provider says a customer owes. Customers also have an account at their provider, and one account has a bill per billing period — and sometimes one per currency.

Two identifiers on every bill

Field	What it is	Unique	What to do with it
billNo	The UniPay bill number, usually the provider number plus its own invoice number — e.g. 4444INV0009. Letters and digits, 4–50 characters.	Within the service provider (one per currency)	Payment processors: send it back when you pay. Treat it as opaque: don’t parse, split or reformat it.
uniqueNo	The service provider’s own internal reference: invoice ID, statement number, case reference.	No	Display it if it helps the customer. Never send it on a payment.

Customers type bill numbers with spaces, dashes and dots; lookups ignore those, so 4444-INV-0009 finds 4444INV0009.

Finding what’s owed

A payment processor can find a bill two ways:

Look up by	When	Needs
Bill number	The customer has a bill in hand.	billNo
Account	The customer knows their account but not a bill — “pay my rates account”.	serviceProvider (its number or short code) and accountNumber

Account numbers are only unique within a provider, so an account lookup always names the provider. An account lookup returns the account’s current bill: the newest bill still owing — so settling this month’s statement while last month’s is unpaid doesn’t report “nothing due” — or, if nothing is owing, its newest bill.

Lookup status

Lookups return a numeric status:

Value	Status	Meaning	Take payment?
1	Owing	The account owes money. bill holds the bill to pay.	Yes
2	NotOwing	Known account, nothing due. bill holds its latest bill.	Only if you allow paying in advance
4	InCredit	Known account, in credit.	Only if you allow paying in advance
3	Unknown	The account exists but its balance is out of date, or it’s closed.	No
0	NotFound	No bill and no account for this number.	No

New statuses may be added. Treat any value you don’t recognise as “don’t take payment”.

What is owed now

A bill’s total can differ from what the account owes today — part may already be paid, through UniPay or at the provider’s own counter. The lookup response carries:

Field	Meaning
bill.totalAmount	The bill as issued.
bill.totalPaid	Paid against it through UniPay so far.
bill.remainingBalance	totalAmount − totalPaid.
amountDueNow	What the account owes right now, including payments made outside UniPay when the provider shares its balances. Negative when in credit.
payableNow	amountDueNow floored at zero: the most to ask the customer for.
balanceIsStale	true when that balance may be out of date.

Show the customer payableNow, not totalAmount. Look the bill up again immediately before taking payment — don’t reuse a lookup from an earlier session, because other channels may have collected in the meantime.

Privacy

When you look a bill up by bill number, the account number comes back masked — every character but the last four replaced with * (123456789 → *****6789). You don’t need the account number to pay; billNo identifies the bill.