Agent Management

Agents in NettPortal are field sellers or resellers who sell hotspot vouchers and collect cash on your behalf. Each agent gets their own login portal (separate from your main admin dashboard), can be limited to specific routers, earns commission on attributed sales, and reports cash back to you through settlements. This guide covers enabling agents, organization-wide settings, creating accounts, the agent portal, commission, settlements, and staff permissions—written so operators and non-technical admins can follow every step.

What is an agent?

An agent is a person who sells your internet access (usually hotspot vouchers) in the field. They sign in at your organization's agent login URL—not the main operator dashboard. You control what they can see (sales, routers, voucher creation) and how much commission they earn. When customers pay through flows linked to that agent, the sale is attributed to them; for cash sales, the agent owes your organization the sale amount minus their commission, tracked through settlements.

Why use agents?

Agents help ISPs and hotspot operators scale sales without giving every seller full admin access:

🛒 Distributed sales

Assign agents to specific routers or sites so they only sell where you allow. Voucher creation uses your existing hotspot packages—price, time limits, and profiles stay under your control.

💰 Commission tracking

Set a default commission rate for the organization and override per agent. Completed payments attributed to an agent automatically store commission rate and amount for reporting.

🏦 Cash collection & settlements

When agents collect cash, they submit settlements (amount, reference, optional receipt photo). You confirm or reject them; confirmed amounts reduce what the agent still owes you.

🔒 Limited portal

Agents never get operator access to routers, billing settings, or customer PII beyond what their role requires. Capabilities are toggled per organization.

Before you start: enable agents

Agents are off by default. Open Agents in the sidebar, click Agents settings (gear icon), or go to Agents → Agents settings. Turn on Enable agents and save. Until this is enabled, agent logins and APIs will not work for your organization.

From the main Agents list you can also use Copy agent login link to share the correct URL with sellers. The link format is: https://your-domain/your-org-slug/agent/login

Agent organization settings

These settings apply to all agents in your organization unless a per-agent override exists (for example commission rate).

Agent permissions

Create vouchers — Off by default. When on, agents can create hotspot vouchers from packages on routers assigned to them. You can still disable voucher creation for individual agents.
Allow custom voucher credentials on agent create — Only applies when voucher creation is on. When enabled, agents may optionally set username and password for a single voucher; when off, codes are always auto-generated.
View sales & commission — On by default. Controls overview KPIs, charts, sales list, and settlements pages in the agent portal.
View assigned routers — On by default. Shows assigned router names on the agent dashboard when enabled.

Agent voucher alerts

Optional notifications when an agent generates vouchers: email only, SMS only, or both. SMS uses your organization's SMS gateway and credits (same as other org SMS). Override email or phone fields are optional; otherwise the system uses your organization email and primary notification or business phone.

Commission & internal notes

Default commission rate (0–1) — Stored as a decimal fraction. For example 0.05 means 5%. You can also enter 5 or 5% when editing an individual agent.
Payout notes — Internal text for your team (not shown to agents). Use for payout schedules, bank details reminders, or policy notes.

Creating and managing agent accounts

Go to Agents → Add agent (or Add your first agent on an empty list). Required fields: display name, username, and password. Optional: login email, phone number, commission override, and router assignments.

Login credentials

Username — Used at agent login (lowercase). Unique within your organization.
Login email (optional) — Real email for invites and recovery. If omitted, the system may use an internal placeholder; email invites require a real address.
Phone (optional) — Digits only; used for SMS login invites. Country code comes from your organization settings when normalizing numbers.
After creation, you can send a login invite by email, SMS, or both with the password you set (modal appears right after add).

Status & commission

Active — Agent can log in; commission applies on attributed sales.
Suspended — Login may still exist but commission on new sales is zero until reactivated.
Commission override — Leave empty to use the organization default. Enter 5 for 5% or 0.05 for the same rate.

Router assignment

Select which routers this agent is tied to. Voucher creation and sales filters respect these assignments—an agent cannot create vouchers on or view sales for routers they are not assigned to.

Per-agent voucher creation

Only available when Create vouchers is enabled in agent organization settings.

This agent can create hotspot vouchers — Uses packages (price, limits, profile) on assigned routers only.
Max vouchers per create (1–500) — Caps each single request; organization hard cap is 500.

Edit agents from the list; delete removes the agent and their login user. Deleting is permanent—confirm only when the account should be fully removed.

The agent portal (what agents see)

After logging in at /your-org/agent/login, agents use a simplified dashboard branded with your organization theme.

Navigation (depends on settings)

Overview — Greeting, and when sales are visible: today/yesterday/month/all-time sales and commission, 7-day charts, settlement summary (due, outstanding, pending), and voucher stock (active, used/redeemed, total).
Settlements — Submit cash paid to you, upload receipt images, view history, withdraw pending submissions. Shown when sales visibility is enabled.
Sales — Filterable list of completed payments attributed to this agent (date, status, source, router, search). Shown when sales visibility is enabled.
Vouchers — List vouchers tied to the agent; create new ones if allowed (pick package, router, quantity; optional custom code/password only when your org allows it).

If you disable View sales & commission, agents still see vouchers (when creation is allowed) but not financial totals or settlement tools.

How sales and commission work

A completed payment counts toward agent stats and settlements when it has your organization ID, the agent's ID, and is not deleted. Commission is calculated from the payment amount and the effective rate (per-agent override, else organization default; suspended agents get 0%).

Attribution

Sales are linked to an agent when the payment is created with that agent ID—for example vouchers the agent created (voucher carries agent ID), or checkout flows that pass the agent through. Agent-created vouchers attribute future redemptions/payments to that agent when the billing layer picks up the voucher's agent ID.

Formula (per agent)

Gross sales — Sum of completed payment amounts attributed to the agent.
Agent commission — Sum of stored commission amounts on those payments.
Due to organization (net) — Gross sales minus agent commission (what the agent should remit for cash collected).

Settlements (agent remittances)

Settlements track money agents hand over to you (cash, mobile money, bank transfer, etc.). In the admin dashboard they appear under Agent settlements in the sidebar (same area as Agents).

Balance fields

Due to organization — Net sales owed (gross minus commission).
Confirmed remitted — Sum of settlements you (or staff) marked Confirmed.
Outstanding — Due to organization minus confirmed remitted (cannot go below zero in displays).
Pending submitted — Amount in settlements awaiting your review (does not reduce outstanding until confirmed).

Agent submits a settlement

On Settlements in the agent portal, they enter amount (in your dashboard display currency, converted to USD internally), a required reference (transaction ID, receipt number, etc.), optional notes, and optional receipt image. They cannot submit more than the current outstanding balance (small tolerance for rounding). Pending settlements can be withdrawn by the agent before you process them.

You review settlements

Open Agent settlements, filter by Pending / Confirmed / Rejected / All, and click a row for details. Staff with permission can:

Confirm — Accepts the settlement; amount reduces the agent's outstanding balance. Optional operator notes are stored for audit.
Reject — Requires a rejection reason; agent sees it in their history.
Record settlement — For cash received in person without an agent submission. Pick the agent, enter amount and reference; can auto-confirm so outstanding updates immediately.

Employee permissions

Operators and super admins always manage settlements. For employees, grant:

View agent settlements — See the queue and details.
Process agent settlements — Confirm, reject, and record settlements.

The Sales Team permission preset includes both. See Employee Management for how presets work.

Settlement statuses

Pending — Submitted by agent or recorded by org, awaiting decision.
Confirmed — Accepted; counts toward remitted totals.
Rejected — Not counted; agent should resubmit if appropriate.

Typical setup workflow

Enable agents and set default commission in Agents settings.
Turn on Create vouchers if agents should issue vouchers; configure alerts if needed.
Create hotspot packages and assign routers.
Add agents, assign routers, enable per-agent voucher creation if needed.
Share the agent login link or send login invites (email/SMS).
Grant employees settlement permissions if someone other than the operator will confirm cash.
Review Agent settlements regularly and confirm or reject submissions.

Best practices

Start with tight permissions

Enable voucher creation only for agents who need it; use max-per-create limits for bulk control.
Keep custom voucher credentials off unless you trust agents to choose codes safely.

Commission clarity

Document payout rules in Payout notes for your staff.
Use per-agent overrides only when rates genuinely differ by seller or location.

Settlement hygiene

Require clear references on every submission so bank/mobile money lines match your books.
Confirm settlements promptly so agent outstanding balances stay accurate.
Use Record settlement for walk-in cash so agents do not need to self-report twice.

Security

Suspend agents who leave instead of leaving active accounts unused.
Send login invites through email/SMS rather than sharing passwords in chat apps when possible.

Troubleshooting

Agent cannot log in — Confirm agents are enabled, account is active, and they use the org-specific agent login URL (not the operator login).

No voucher create button — Enable Create vouchers in agent org settings and per-agent voucher creation; assign at least one router and ensure packages exist for that router.

Sales or settlements missing in agent portal — Check View sales & commission in agent organization settings.

Outstanding balance looks wrong — Only completed attributed payments count; only confirmed settlements reduce outstanding. Rejected or pending items do not count as paid.

Employee cannot confirm settlements — Add Process agent settlements permission on their employee profile.

Next steps

Configure Voucher Management and Package Management so agents sell the right plans.
Set up Employee Management if staff will help confirm settlements.
Review Router Management before assigning routers to agents.

Documentation