Payment Forwarder

Payment Forwarder connects a dedicated Android phone containing a merchant SIM to ISPbills. The standalone ISPbills SMS Forwarder app reads supported merchant SMS and app notifications, sends normalized payment events to ISPbills, and helps match inbound collections to pending payments.

The current device page lists bKash, Nagad, Rocket, Upay, mCash and CellFin as supported wallets. Message parsing depends on the format received from the wallet. Refund, reversal, debit, cash-out and outgoing send-money messages are retained for review but are never auto-credited.

Access and prerequisites

Only authenticated users with the developer, super_admin or group_admin role can open and operate the admin Payment Forwarder page. Events and devices are limited to the selected operator scope; a Group Admin is always limited to its own operator account.

Before setup, prepare:

• an Android phone with the merchant SIM and internet access;
• the exact merchant number that receives wallet messages;
• permission to install the APK directly from the ISPbills server;
• access to Bills & Payments → Payment Forwarder.

Register the device

1. Open Bills & Payments → Payment Forwarder, or /admin/payment-forwarder on your ISPbills server.
2. Download sms.apk from /sms.apk.
3. Under Register Device, enter a recognizable Name and the exact Merchant Number.
4. Select Register Device.

Use the exact merchant number shown by the wallet provider. ISPbills links the device to the corresponding payment gateway.

Configure the Android phone

1. Install sms.apk on the phone containing the merchant SIM. If Android blocks it, allow installation from the browser or file manager used to open the APK.
2. Open ISPbills SMS Forwarder. This is separate from the main ISPbills Android app.
3. Enter the ISPbills Server URL and the same Merchant number used during registration.
4. Select Save and start. There is no provider selector.
5. Grant SMS receive/read permission and, on Android 13 or later, foreground notification permission.
6. Open notification access settings and enable ISPbills SMS Forwarder so supported wallet-app alerts can be read.
7. Exempt the app from battery optimization by choosing Unrestricted, No restrictions, or the equivalent vendor setting. Enable auto-start on boot when the phone provides that option.
8. Leave the foreground-service notification enabled.

Use the app's Required permissions card to reopen notification access, battery, or app settings when a permission was previously denied.

Confirm device health

The Registered Devices table shows the merchant number, app version, last contact, battery level, Android ID, last IP and reported diagnostics. A device is Online when ISPbills received a heartbeat in the last 20 minutes; otherwise it is Offline. Online status confirms recent communication, not that every merchant message was parsed or matched.

The forwarder sends payment events and device health information securely to ISPbills. Do not share device registration information outside the merchant-phone setup process.

Understand event statuses

Status	Meaning
received	ISPbills stored the event but has not finalized reconciliation.
matched	One or more amount-based candidates exist, but the match is partial or ambiguous and needs review.
unmatched	No safe pending-payment match was found, no matching merchant gateway exists, or the message is not an inbound collection.
auto_approved	ISPbills found one safe match, or safely created a tracked payment from a unique customer signal, and processed it.
manually_approved	An authorized admin selected a pending payment or entered a customer ID and approved it.
duplicate	The transaction duplicates a previously linked event and is not credited again.
rejected	An admin reviewed and rejected the event; no payment is credited from it.

The dashboard's Needs Review metric combines received, matched and unmatched events.

How reconciliation works

ISPbills compares the merchant, amount, payer and transaction references with pending payments. It processes a payment automatically only when it can identify one safe match. Ambiguous or unexpected events remain available for manual review.

When approved, ISPbills marks the linked payment Successful, copies the payer and transaction details, processes the payment through the normal payment workflow, and records the approval time. Automatic approvals have no admin in Approved by; manual approvals record the approving operator.

Review and resolve an event

1. Open Forwarded Events and select Review on the event.
2. Compare amount, payer, merchant, reference, transaction type, raw message and Match reason with the merchant wallet.
3. If payment or customer information was added after the event arrived, select Recheck. Finalized auto-approved, manually approved or rejected events are not rematched.
4. To approve an existing payment, choose one Pending recharge payment and select Approve / Match.
5. If no pending row exists but the customer is known, enter the exact Customer ID instead. ISPbills creates a tracked iPay customer-payment row from the forwarded transaction and then processes it.
6. Enter either a pending payment or a customer ID, never both. Only a pending payment in the same operator scope can be manually approved.
7. Select Reject when the event is invalid or must not be credited. Finalized and duplicate events do not offer manual approval or rejection controls.

Filter events and search customers

Use Toggle Filters on the web page to filter by exact status and transaction date range. The Payer, merchant, ref… search checks payer number, merchant number, reference number, client event UUID and raw message text. It does not directly search the linked customer's name, username, mobile or profile.

Customer search in the Android forwarder is a separate tool. It searches the device's operator-scoped customer list by name, username, mobile, IP or MAC and can open customer details. Its call, SMS and copy actions are local to the phone; opening the web customer profile still requires a normal ISPbills web login. Do not confuse that customer lookup with event reconciliation or the web event filter.

Daily checks

• Keep the device Online and review its diagnostics.
• Clear Needs Review events after checking the merchant wallet.
• Confirm approved totals against the wallet statement and customer payment history.
• Investigate repeated duplicates rather than approving another row.
• Install an update when the app displays Download update.

Troubleshooting

Problem	Check
Device shows Offline	Confirm mobile data/Wi-Fi and the server URL, then set battery use to Unrestricted and reopen the app. Also confirm the registered and app merchant numbers are the same.
Device registration is rejected	Confirm the merchant number matches the active registered device. Re-register the device if necessary.
SMS arrives but no event appears	Grant SMS receive/read permission, keep the service running, and confirm the message contains a parseable amount.
Wallet-app notification is missing	Enable ISPbills SMS Forwarder under Android notification access; normal notification permission alone is not notification-listener access.
Event remains unmatched	Compare the merchant number, amount, payer and reference with the pending payment, then use Recheck.
Search cannot find a customer	The event search is not a customer-profile search. Search by payer/reference/raw text, or use the Android customer list and then enter the exact Customer ID during manual review.
Several candidates appear	Verify the merchant transaction externally and choose the correct pending payment. ISPbills intentionally avoids auto-approval when the result is ambiguous.
Duplicate message appears	Compare the payer, amount and reference. Do not manually credit a duplicate delivery.
Forward failed remains visible	Check the displayed HTTP/network reason. Version 1.0.6 and later clears an old failure after a successful forward.
APK will not install	Allow APK installation for the browser/file manager that opened /sms.apk, then download it again from the ISPbills server.

Security and maintenance

Keep the phone locked, restrict notification access, and do not expose diagnostics or transaction screenshots unnecessarily. Install updates only from the Payment Forwarder page in your own ISPbills account.