ImaraISPPayment states
What each payment state means, which transitions are allowed, and why a written-off payment never becomes paid on its own
Every payment in ImaraISP, whether it came from a phone prompt, money paid in directly to your business number, a card, or a cashier's Mark paid, moves through the same small set of states. The state word is what you see in the Payments list, in a customer's history, and in the subscriber's portal.
The states
| State | Meaning | What you see and do |
|---|---|---|
| INITIATING | ImaraISP is asking the provider to start the payment (for example sending the M-Pesa prompt). Lasts a second or two. | A spinner on Pay now. Nothing to do. |
| PENDING | The provider accepted the request and we are waiting for the subscriber to confirm, or for the provider's confirmation to arrive. | The live countdown on Pay now with the settle-source chips (STK, IPN, poll). Wait, or use the fallback: "Paid at Paybill" or "Cash". |
| PAID | Money confirmed and added to the customer's credit. When the credit covers a plan period, the service has been extended and the router told to reconnect the subscriber. | Green, with the receipt number. The customer should be online within seconds. This is final. |
| FAILED | The provider told us the charge did not happen: the subscriber cancelled, entered a wrong PIN, or timed out on the phone. | Try again with a new payment. Do not tell the subscriber "nothing was charged" until you have checked; see below. |
| UNMATCHED | Money arrived but ImaraISP could not safely tie it to a customer and a service. | It sits in the Unmatched queue on Payments. A cashier picks the customer and matches it. |
| EXPIRED | The waiting window closed with no confirmation. | Same as FAILED for the subscriber. If the money shows up later it still settles; see below. |
| REVERSED | A paid amount was later reversed by the provider or refunded by you. | Final. The money is taken back out of the customer's credit and the plan periods it bought are voided. The balance can go below zero and shows as Owed. |
Why a payment lands in UNMATCHED
The row carries a short reason so the cashier knows what to check:
| Reason | What happened |
|---|---|
no-match | The reference the payer typed matched no account number, phone or username. Usually a typo in the account number. A reference that matches nobody is never matched to the payer's own phone. |
ambiguous-phone | The reference is a phone number that is on several customers. |
ambiguous-ref | A phone-shaped reference matches one customer's phone and another customer's username. |
currency-mismatch | The payment is in a different currency from your ISP's. ImaraISP never converts it. |
short-paid | A prompt was paid for less than it asked for. |
charged-after-failed | We had already marked the payment FAILED, then the provider confirmed a charge. See the next section. |
Matching an unmatched payment credits that customer and buys whole plan periods from their credit, like any payment. See How customers pay.
Allowed transitions
A payment may only move along these arrows. Anything else is refused, even if two confirmations arrive at the same moment.
| From | Can become |
|---|---|
| INITIATING | PENDING, FAILED |
| PENDING | PAID, FAILED, UNMATCHED, EXPIRED |
| PAID | REVERSED only |
| FAILED | UNMATCHED only |
| UNMATCHED | PAID (by a human match) |
| EXPIRED | PAID (late success) |
| REVERSED | nothing; final |
Three consequences worth remembering:
- PAID is final. Nothing can take a paid payment back to pending or failed. The only way out is REVERSED, which records that the money went back.
- A retry is a new payment, not a change to the old one. If a subscriber cancelled the phone prompt, press Pay now again and a fresh payment is created.
- UNMATCHED only ever leaves through a person. There is no automatic re-match.
Why FAILED never becomes PAID
Providers sometimes say "abandoned" or "failed" while the subscriber is still on the phone. If ImaraISP believed that and closed the payment, and the real confirmation arrived a moment later, the money would have nowhere to go.
So the rule is:
A charge on a written-off payment goes to UNMATCHED, never to PAID
When a provider confirms a charge on a payment we already marked FAILED, the payment
moves to UNMATCHED with the reason charged-after-failed. It lands in the Unmatched
queue for a cashier. Money is never discarded, and service is never granted without a
person deciding.
What this means at the desk:
- Never tell a subscriber "nothing was charged" just because the app shows FAILED. Say "if the money left your phone, it will appear in our queue and we will apply it".
- Check the Unmatched queue before re-charging someone who says they already paid. Matching the queued payment is faster than a second charge and a refund.
Late success after EXPIRED
Money is money. If a payment expired because the provider's confirmation was slow, and the provider later confirms it, the payment moves from EXPIRED to PAID and the service is extended as if it had settled on time. You do not need to do anything. If the subscriber has already paid again in the meantime, the second payment also settles, and the service is extended twice.
Duplicates
Two things can announce the same payment: the provider's callback, and ImaraISP's own check that asks the provider "did this go through?".
- Whichever arrives first wins and settles the payment.
- The second one is recognised as a duplicate and does nothing. The subscriber is not extended twice and the ledger is not charged twice.
The receipt is the key
The provider's receipt (for example an M-Pesa code like SJK4H2X9QR) is the identity of a payment in ImaraISP.
- Two payments can never share a receipt. An attempt to record the same receipt twice is treated as a duplicate.
- When ImaraISP has no receipt yet (the provider confirmed the payment before sending the receipt), the payment can still settle, and the receipt is filled in when it arrives. A receipt is never overwritten once set.
- Mark paid (cash or bank) has no provider receipt. The cashier may enter one (a bank slip number, for example); it is optional, and if given it plays the same role.
The Payments search box accepts "Ref, phone or name". Paste the receipt code when a subscriber sends you a screenshot of their payment confirmation. It is the fastest way to find exactly that payment.
What happens after PAID
In order, within a few seconds:
- The payment is added to the customer's credit.
- Whole plan periods are bought from that credit, and the service's expiry is extended by one plan period for each. Anything left over stays as credit.
- The router is told to reconnect the subscriber, so they come online without logging in again.
- The portal, if the subscriber is watching it, logs the device in automatically.
If the payment is less than a plan period, it stays as credit and steps 3 and 4 do not happen yet.
If step 3 fails (router offline), the subscriber connects normally the next time they log in; the money and the extension are already safe. Use "Reconnect" on the customer once the router is back.
Your own subscription does not affect this
If your ImaraISP subscription is past due or suspended, subscriber payments still settle, provider callbacks are still processed, cashiers can still Mark paid, and subscribers keep logging in. Your subscribers are never cut off because of your account with the platform.