← Back

ZamZam SchoolPay API

Query, Quote, and Pay endpoints for school fee payments.

Base URL

https://zamzamtest.santimschool.com/api/v1

Authentication (API Key)

Send your key in X-Api-Key or Authorization: Bearer .... Keys are created in the Admin Panel and can be scoped to query, quote, and/or pay.

curl -H "X-Api-Key: YOUR_KEY" "https://zamzamtest.santimschool.com/api/v1/students/STU-123/query"

1) Query — check student payment info

GET /api/v1/students/{studentId}/query

  • include: comma-separated fields (default: summary + charges as returned by service).
  • chargeFilter: all, open, payable, paid, optional
  • sourceTypes: fee_plan, fee_assignment, penalty, adhoc (comma-separated)
  • syncPenalties: true/false (default true)
  • paymentLimit: limit payment history rows (default 20)
curl -H "X-Api-Key: YOUR_KEY" \ "https://zamzamtest.santimschool.com/api/v1/students/STU-123/query?include=summary,charges,openCharges&chargeFilter=payable"

2) Quote — select periods/charges and lock the total

POST /api/v1/quote

Quote is short-lived (default 30 minutes, configurable by ttlMinutes). You can select billing “periods” in flexible ways using selection.mode.

Common fields

  • studentId (required)
  • ttlMinutes (optional, default 30)
  • amount (optional): expected total; server verifies sum matches within tolerance

selection.mode options

  • charge_ids (default): selection.chargeIds as an array of studentChargeId.
  • installment_ids: selection.installmentIds selects tuition installments by feePlanInstallmentId. Optional: selection.includePenalties (default true).
  • all_open: applies every currently open charge.
  • auto_amount: selection.amount (server allocates in allocation order).
  • due_date_range: selection.startDate and selection.endDate (inclusive, format YYYY-MM-DD). Optional: selection.includePenalties (default true).
POST https://zamzamtest.santimschool.com/api/v1/quote { "studentId": "STU-123", "ttlMinutes": 30, "selection": { "mode": "due_date_range", "startDate": "2026-07-01", "endDate": "2026-09-30", "includePenalties": true } }

3) Pay — confirm paid amount

POST /api/v1/pay

To be safe against retries, use reference as an idempotency key. If the same key is sent again, the server returns the existing payment.

Using a quote (recommended)

curl -X POST \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_KEY" \ -d '{ "quoteId": "PUT_QUOTE_ID_HERE", "reference": "TXN-998877", "method": "bank", "paidAt": "2026-07-08T12:30:00Z", "notes": "Mobile banking" }' \ "https://zamzamtest.santimschool.com/api/v1/pay"

Without quote

Send studentId and either: (a) allocations (chargeId -> amount), or (b) selection + amount.

Error format

{ "ok": false, "error": "message", "code": 401 }