Payniva Platform Guide

Platform Overview

Payniva is a payment collection platform with two portals — School Portal and Organization Portal — each scoped to their own data, and connected to Pakistan's national 1LINK/1BILL payment network.

Schools use Payniva to manage student fee collection, generate payment vouchers, receive payment confirmations, and maintain a complete payment ledger. Organizations (exam authorities, hospitals, government bodies) use Payniva to connect their own systems to the payment network.

How It's Built

Payniva is a REST API server with separate frontend portals for schools and organizations. The API handles all payment logic, connects to the 1LINK/1BILL network, and keeps each organization's data completely separate.

The server-side handles payment creation, status lookups, confirmation receipts from the banking network, and ledger updates. The frontend portals are the dashboards that school finance staff and organization users log into.

Managing Organizations

Each school or organization connected to Payniva is registered as a separate entity on the payment network. The platform administrator manages which organizations are active on the platform.

• States: Created → Active → Suspended
• Identifier: Each organization gets a unique reference code registered with the payment network
• Suspending: Stops new payments but preserves all historical records

User Management

The platform administrator can create user accounts with specific roles. Each user's role determines what they can see and do within their organization's portal.

Roles include: Finance Manager, School Administrator, Cashier, Teacher (class view only), and Organization User. Each role is limited to the data of the organization they belong to.

Activity Log

Every significant action taken in Payniva is recorded in an activity log. This includes creating fees, recording payments, changing user access, and any data exports. Each entry includes:

• Date & Time — when the action occurred
• Who did it — the staff member's name and role
• What happened — a plain description of the action
• Which record — the specific student, payment, or fee affected

Fee Plans

Fee plans define the payment amount, due date, and applicable student cohort. Each fee plan generates a batch of invoices — one per student in scope.

Fee plans can be:

• Annual — full year fee in one invoice
• Quarterly — four invoices per year
• Custom — one-time or irregular amounts

Invoices & Payment Vouchers

Creating an invoice for a student automatically generates a payment voucher number via the 1BILL registration. This voucher number is printed on the fee slip and can be given to the student directly.

Once a payment voucher is issued, the student can pay using that number at any 1LINK-connected bank — ATM, mobile app, internet banking, or over the counter.

Ledger & Payment Records

Confirmed payments are automatically recorded in the payment ledger. Each record contains:

• Student reference
• Invoice and payment voucher number
• Amount paid and payment channel used
• Bank-side transaction reference for traceability
• Date, time, and confirmation status

Finance managers can export payment reports in CSV or PDF at any time.

Creating Payment Batches (Organization)

A payment batch represents an exam session, recruitment cycle, or any collection period. It defines the fee amount, payment deadline, and reference for that group of applicants or participants.

Once a batch is created, your system can register individual applicants against it and issue payment vouchers for each one.

Payment Requests (Organization)

Your source system calls POST /api/payments/create to register an applicant for payment. Payniva generates and returns a payment voucher number. Store this in your source system to track payment status.

Automatic Confirmations (Organization)

After a payment is made at a bank channel, the banking network sends a confirmation to Payniva. Payniva verifies the confirmation, updates the payment status, and automatically notifies your source system.

See How It Works for the full payment flow diagram.

Authentication

All portal API endpoints require a valid authentication token passed in the request header. Tokens expire after 15 minutes for security. A refresh mechanism allows sessions to continue without re-entering credentials repeatedly.

Payment network endpoints (/api/bill/*, /api/payment/callback) use cryptographic signature verification instead of user tokens. These are server-to-server endpoints, not user-facing.

Payment Network Endpoints

Organization Endpoints

School Endpoints

Data Separation

Every school and organization has a completely isolated data space. Users can only access data for their own organization. See Security & Privacy for the full explanation of how access control works.

Payment Verification

Every payment confirmation received from the banking network is cryptographically verified before being recorded. Unverified or tampered confirmations are rejected and logged. This prevents any fake or duplicate payment records from being created.

Login & Sessions

Login sessions expire automatically after 15 minutes of inactivity. A background refresh mechanism keeps active users logged in without interruption. Inactive sessions are terminated automatically. All login events are logged.

Changelog