Troubleshooting & Common Issues
Download the Tontiin app to access both traditional savings and modern financial services.
Module 11 — Troubleshooting & Common Issues
Audience: Customer Success & Sales Agents
Goal: Diagnose and resolve the most common issues customers report, with step-by-step fixes for each.
How to Use This Module
For every customer issue, start with these three questions before going deeper:
1. What exactly is happening? (error message, screen, action they were taking)
2. When did it start? (first time, after an update, after a specific action)
3. What device and version? (Android/iOS, app version shown in Account tab)
Section 1 — Login & Account Issues
1.1 — "I can't log in / wrong password"
Steps:
1. Confirm the phone number includes the country code (e.g. +237612345678 not 0612345678)
2. Ask the customer to use Forgot Password on the Login screen
3. They enter their phone number → receive an SMS code → set a new password
4. If no SMS is received, ask: is the phone number correct? Is the phone receiving SMS from other senders?
If the phone number was changed: The customer must contact support to update the phone number linked to their account.
1.2 — "I never received the SMS verification code" (password reset only)
SMS codes are only used during password recovery, not during signup. If a customer says they never received a code:
Steps:
1. Confirm the phone number entered includes the country code
2. Check if the phone's SMS inbox is full (old phones sometimes block new messages when full)
3. Ask the customer to wait 1–2 minutes — SMS delivery can be delayed
4. Check if the phone is on airplane mode or has no signal
5. Try the Forgot Password flow again from the beginning
Note: SmartSell uses standard SMS for password recovery. The code will come as a plain text message. Signup no longer uses any SMS code — if a customer says they are waiting for a signup code, they are on an outdated version of the app and should update it.
1.3 — "My biometric login stopped working"
Steps:
1. Check if the phone's fingerprint or face unlock is still working in the phone's own settings
2. If the phone was reset or a new fingerprint was added, biometrics in SmartSell need to be re-enabled
3. Go to Account tab → Security → toggle Biometrics off, then back on and confirm with the biometric scan
1.4 — "I was removed from a business / I can't see my business"
Steps:
1. Check the Dashboard — is the business card still visible?
2. If not, confirm with the business owner that the employee is still active (not deactivated)
3. If the employee was deactivated, the owner must reactivate them from Employees List → Employee Detail → Activate
Section 2 — POS Issues
2.1 — "The POS is stuck loading / bootstrap never completes"
Steps:
1. Check internet connection — bootstrap requires a live connection the first time
2. Close the app completely and reopen it
3. Try connecting to a different network (Wi-Fi instead of mobile data, or vice versa)
4. If the app was recently updated, the bootstrap may need to re-download — give it a minute
2.2 — "A product is not showing in POS search"
Possible causes and fixes:
| Cause | Fix |
|---|---|
| Product does not exist in catalog | Go to Products → verify the product exists. If not, create it. |
| Product is inactive | Go to Product Detail on the web portal and check if the product is marked inactive. Reactivate it. |
| POS data is outdated (cached) | Open the POS menu (⋮) → trigger a manual resync or restart the POS |
| Barcode was searched but not assigned to product | Search by name instead. Then update the product's barcode field. |
2.3 — "Barcode scan is not working"
Steps:
1. Check camera permission: Phone Settings → SmartSell → Camera → must be Allowed
2. Check that the barcode is clean and undamaged — wrinkled or scratched barcodes may not scan
3. Ensure adequate lighting — poor light causes scan failures
4. Try typing the barcode number manually in the search bar instead
5. If the scan reads but no product is found, the barcode is not linked to any product — update the product's barcode field
2.4 — "Sales are not showing in reports"
Most common cause: The device was offline when the sales were made and they have not synced yet.
Steps:
1. Open the POS for that branch
2. Check if a Resync button is visible — if yes, the device has pending (unsynced) sales
3. Ensure the device has internet
4. Tap the Resync button
5. Wait for the sync toast confirmation
6. Open Reports — the sales should now appear
If resync completes but sales still don't appear, ask the customer for the approximate date and time of the missing sales and escalate to support with that information.
2.5 — "The wrong price is showing in POS"
Steps:
1. This means the POS bootstrap data has an old price cached
2. Go to Products → Product Detail and confirm the current selling price
3. If the price in the catalog is correct, the POS just needs to refresh — tap the resync option in the POS menu (⋮)
4. If the price in the catalog is wrong, edit the product and update it, then resync the POS
2.6 — "Stock shows as negative"
Cause: A sale was processed for a product with zero stock. SmartSell does not block sales based on stock levels.
Steps:
1. This is an expected state — no error
2. Direct the customer to Manage Stock and add the correct quantity
3. The stock movement log will show the sale that caused the negative and the correction
Section 3 — Inventory & Stock Issues
3.1 — "Stock I added is not showing"
Steps:
1. Confirm the stock was added to the correct branch (not a different branch or warehouse)
2. Pull to refresh on the Manage Stock screen
3. Search for the exact product again — confirm the search term is correct
4. If stock was added via web portal, refresh the mobile app
3.2 — "Stock numbers don't match physical count"
Steps:
1. Open Stock Movements and filter by the product in question
2. Trace every movement from the last known correct date
3. Look for any unexpected outbound movements (sales, transfers, adjustments)
4. Identify the discrepancy, then use Manage Stock to add the correct quantity with a note explaining the correction
3.3 — "I accidentally reset the wrong branch's stock"
This is a critical situation. Stock reset is irreversible from within the app.
Steps:
1. Do not attempt any further changes
2. Escalate immediately to your team lead or support engineering
3. Provide: business name, branch name, approximate time of the reset, and who performed it
4. Support may be able to restore from a backup depending on timing
Section 4 — Credits Issues
4.1 — "I can't create a credit sale — it asks for a phone number"
Cause: The customer phone number field is mandatory for credits. This is by design.
Explanation to customer: SmartSell requires a phone number to link the credit to a customer. Without it, there is no way to track who owes the money. If the customer refuses to provide their number, the transaction must be processed as a cash sale.
4.2 — "A credit still shows as Not Paid after the customer paid"
Steps:
1. Open the Credit Detail screen for that credit
2. Check the Payment History section — confirm the payment was actually recorded
3. If no payment appears, tap Add Payment and record the payment now
4. If the payment was recorded but the status did not update, refresh the screen (pull to refresh or navigate away and back)
Section 5 — Employee & Access Issues
5.1 — "A cashier can't see the POS / lands on a blank screen"
Most common cause: The cashier has the Sales role but has no branch assigned.
Steps:
1. Go to Employees List → Employee Detail for that cashier
2. Check their Branch assignment
3. If it is blank, tap Edit and assign the correct branch
4. The cashier logs out and back in — they should now land on the POS for their assigned branch
5.2 — "An employee is not receiving their login credentials"
Steps:
1. Confirm the phone number was entered correctly when creating the employee
2. Check if the employee already had a SmartSell account — if so, they use their existing credentials
3. If the number was wrong, edit the employee record with the correct number
4. The employee can also use Forgot Password on the login screen to set up access independently
Section 6 — App & Device Issues
6.1 — "The app is crashing"
Steps:
1. Check the app version in Account tab → bottom of screen
2. Go to the app store and update to the latest version
3. Restart the phone
4. If crashing persists on a specific screen, note exactly which screen and action triggers the crash and report to support
6.2 — "The app is very slow"
Steps:
1. Check available storage on the phone — low storage causes slowdowns
2. Check internet connection speed — slow connectivity affects loading
3. Close other apps running in the background
4. If the POS is slow, the bootstrap cache may be large — a full resync can help
6.3 — "Push notifications are not arriving"
Steps:
1. Go to Account tab → Push Notifications card
2. Check the permission status shown
3. If status is Denied, tap Open Settings and enable notifications at the device level
4. If status is Granted but notifications still don't arrive, tap Refresh to re-register the device's push token
5. Check that the phone is not in Do Not Disturb mode
Escalation Guide
Escalate to your team lead or support engineering when:
- A stock reset was performed on the wrong branch/warehouse
- A customer cannot log in and Forgot Password is not resolving it (e.g. no longer has access to the phone number)
- Sales are missing from reports and a resync did not resolve it
- A customer's business or account data appears to be corrupted or missing
- Any billing or payment disputes
When escalating, always provide:
- Customer name and phone number
- Business name
- Exact issue description
- Steps already tried
- Approximate date/time of the incident
Previous Module → 10 — Subscriptions & Billing
Next Module → 12 — Sales Playbook & Objection Handling