Online payments and dunning

Which payment gateways are wired, what simulated mode really records, how the dunning ladder escalates, and what autopay, tax settings, waivers and refunds actually do.

Fees & finance guide for day and boarding schools.

Last updated August 29, 2026

What this is for

Counter collection works with no configuration at all. This page covers the parts a school switches on afterwards: letting families pay themselves, chasing the ones who do not, adding a tax line to receipts, and reversing money that should not have been taken. Decide the checkout mode during setup, before you tell parents that online payment exists, because the mode is read from the environment and changing it needs a redeploy rather than a settings save.

Which gateways are actually wired

Mode	Environment	What happens at checkout
simulated	FEES_ONLINE_PAYMENT_MODE=simulated	No gateway call. Records a real payment for the full outstanding balance, tagged [SIMULATED_GATEWAY] with a SIM- transaction id
razorpay	RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET, NEXT_PUBLIC_RAZORPAY_KEY_ID	Razorpay Orders API with the in-page widget, signature verification, and an optional webhook using RAZORPAY_WEBHOOK_SECRET
stripe	STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, STRIPE_CURRENCY	Stripe Checkout by redirect, verified on return and by webhook using STRIPE_WEBHOOK_SECRET
telr	TELR_STORE_ID, TELR_AUTH_KEY, TELR_CURRENCY	Telr Hosted Payment Page by redirect, confirmed with an order status check. TELR_TEST_MODE=1 for test transactions
disabled	FEES_ONLINE_PAYMENT_MODE=disabled or unset	The pay-online page shows an unavailable notice

Razorpay, Stripe and Telr are the three live gateways; Paystack appears in the gateway catalogue as roadmap only and cannot be selected. Whichever you pick, mirror the value in NEXT_PUBLIC_FEES_ONLINE_PAYMENT_MODE, because the parent-facing page decides whether to render at all from the public variable while the API routes check the server one - a mismatch produces either a dead button or a page that refuses every attempt. Open /fees/settings/payment-gateway to see the resolved mode, which keys are present, and which gateways suit the school region inferred from its timezone and board. No secret values are shown there.

The dunning ladder, and what each step really sends

Default step	Configured channels	What the family actually receives
1 day overdue	IN_APP	An in-app notification on the student account
7 days overdue	IN_APP, EMAIL	The notification, plus a reminder email to the primary guardian
15 days overdue	IN_APP, EMAIL, SMS	As above. The bundled SMS provider writes a server log line and reports success, so nothing is texted
30 days overdue	IN_APP, EMAIL, SMS, WHATSAPP	As above, plus an in-app note holding a wa.me link for a member of staff to open by hand

Edit the steps at /fees/settings/dunning, then use Preview affected to see how many fee lines and students the next run would touch before you commit to it. A run only advances an instance when the matching step is further along than the step already stored on it, so running twice in one day does not double-chase. Advancing sets the stored step and the last-contacted time and flips the instance to OVERDUE, which is what fills the dunning columns on /fees/defaulters. None of it happens on its own: the ladder advances only when POST /api/fees/dunning/run is called, which in normal operation means the daily job.

Tax lines, waivers and refunds

/fees/settings/gst - Indian GST. Off by default at a zero rate; enabling it adds CGST and SGST, or IGST when the school is marked inter-state, and numbers tax invoices INV-YYYY-00001.
/fees/settings/vat - Gulf VAT. Off by default at 5% in AED, with its own TAX-YYYY-00001 invoice series and the school TRN on the document.
/fees/settings/late-fees - a percentage or flat penalty per day past a grace period, with a cap. It is shown at the counter as "if paid today" and is never added to the balance.
/fees/waivers - concessions. Created PENDING and inert; a second person must approve it, and Principal or Vice Principal must approve anything high value, which defaults to ten thousand rupees or a quarter of the line and is tunable with FEE_HIGH_VALUE_ADJUSTMENT_INR.
/fees/refunds - PENDING, then APPROVED by somebody else, then COMPLETED by finance. Completion marks the original payment refunded and recomputes the fee instance; the gateway is not called, so the money is moved by hand.

Limits

Only in-app notifications and SMTP email leave the server. Any SMS count in a run result means logged, not delivered, and WhatsApp is a click-to-chat link for a human.
A waiver attached to a fee type rather than to a specific fee instance is recorded and approved but reduces no balance. Attach it to the instance you mean.
Completing a refund marks the whole payment refunded even when the refund was for part of it, so the full amount drops out of the paid total. Record part refunds knowing that.
Changing the checkout mode is an environment change, not a settings change, and needs a restart or redeploy on both the server and the public mirror.

Common questions

Quick answers in plain language.

Which payment gateways can a school actually use today?+

Razorpay for India, Stripe for card checkout in the United States, United Kingdom, Singapore and the EU, and Telr for the UAE and the Gulf. All three are wired end to end with verification and webhook capture. Paystack is listed in the gateway catalogue as roadmap and cannot be selected. Simulated mode and plain counter collection are the two options that need no gateway account.

The pay-online page says online payment is unavailable even though keys are set. Why?+

The page decides from NEXT_PUBLIC_FEES_ONLINE_PAYMENT_MODE, which is read at build time, while the API routes read FEES_ONLINE_PAYMENT_MODE. Setting only the server variable leaves the page gated. Set both to the same value, redeploy, then confirm the resolved mode and the key checklist at /fees/settings/payment-gateway.

Is the late fee configured at /fees/settings/late-fees ever charged?+

No. It is calculated and shown in the collection dialog as the amount that would be due if the family paid today, and it is never written to the fee instance - the lateFineAmount field is not set by any application route. A payment above the outstanding balance is also rejected, so a penalty cannot be collected on the same line. Schools that must charge it add a separate fee instance for the penalty.

Who can approve a large fee waiver?+

Not the person who raised it - that returns 403. Ordinary waivers can be decided by Platform Admin, Principal or Vice Principal; anything high value needs Principal or Vice Principal specifically. High value means the absolute amount reaches the FEE_HIGH_VALUE_ADJUSTMENT_INR limit, ten thousand rupees by default, or the waiver is worth 25% or more of the line.