Control Numbers
Tanzanian bill and customer reference numbers, and how TeePay verifies payments made to them.
A Control Number is a payment reference issued through TeePay's Tanzanian provider. Your customer pays it from their bank or mobile wallet, at any time and from any channel that supports it, and TeePay matches each payment to the number.
Kinds of numbers
kind | Use it for | Amount |
|---|---|---|
bill | One bill, invoice or fee | amount_minor is required |
customer | A reusable number for one customer, paid repeatedly | Optional, with a payment_mode |
For customer numbers, payment_mode controls what is accepted:
EXACT: each payment must equalamount_minor.ALLOW_PARTIAL_AND_OVER_PAYMENT: any amount, optionally capped withmaximum_minor.
Eligibility
- Available to Tanzanian businesses in TZS.
- TeePay must approve Control Number access for your account. Until then
features.control_number_createisfalseand creation returns403. - Your account has daily and monthly creation quotas, and the API allows up to 10 creations per minute.
From payment to money received
A payment to a Control Number goes through several stages before it is money you can use:
Payment notification
The provider reports that a payment was made. This is a claim, not proof. It appears as
pending_verification.
Verification
TeePay confirms the payment with the provider and checks the number, amount and currency. A payment
that cannot be confirmed automatically appears as under_review until TeePay's team resolves it.
Verified and ledger-posted
Once confirmed, the payment is posted to your ledger with its fee and becomes verified. Only now does
it count toward collected_minor, and only now is the payment.completed webhook sent.
Only verified payments are money received
Never release goods or services on pending_verification or under_review. Those payments have no
amount in the API on purpose.
Payer and beneficiary
The name on a Control Number is the beneficiary you issued it for (for example a student). The person who pays may be someone else (a parent). TeePay never presents the beneficiary as the payer.