Handoff checklist for school developers

What ConfirmApp does vs what you build

• ConfirmApp captures real M-PESA confirmation SMS on the official handset, applies Admin-configured provider rules, and exposes payments through the integration API and optional webhooks.
• Your school finance application remains the system of record for students, fee balances, PDF receipts, parent messaging, and reporting. ConfirmApp does not replace those features.
• Sharing the same cloud project as the school app does not automatically write payments into your fee ledger. You still implement a small bridge (poll, webhook consumer, or internal job) that maps ConfirmApp events into your models.

1. Credentials and settings (from operator)

Confirm your integrator package before writing code. Missing any item blocks end-to-end testing.

• Base URL for the integration API (production host you were given).
• Client code header x-client-code for this school tenant.
• Integration key header x-integration-key from Admin, Developer block.
• Webhook secret (if using push): URL registered in Admin and secret used to verify x-confirmapp-signature.
• Field process: which SIM or office phone runs the APK, and who owns APK updates.

2. Choose an integration shape

Pick one primary path. Mixing without idempotency causes duplicate fee postings.

• Poll + claim: your backend calls GET /api/integration/live, matches a payment to a student or invoice, then calls POST /api/integration/claim with your reference (for example admission or invoice id). Good when you already run scheduled workers.
• Webhook after claim: cashier or automation claims in your flow first, or you claim from a worker, then consume payment.claimed to post into the ledger and issue receipts. Verify signatures on every request.
• Parallel SMS pipeline: if your school stack already ingests raw SMS through its own HTTP endpoint, keep that separate from ConfirmApp unless product explicitly merges both. Document which path is authoritative for duplicate detection.

3. Your application responsibilities

• Match payments to students using paybill account text, references, or amounts plus phone, according to your rules.
• Idempotency: store and dedupe by M-PESA transaction code so retries never double-post a fee credit.
• Partial payments: understand claimedKes and remainingKes if you split claims across invoices.
• Receipts and parent comms: generate PDFs and notifications from your stack after you accept the payment record.
• Secrets: never put integration keys or webhook secrets in a public app or browser bundle. Call ConfirmApp from your server.

4. Testing before go-live

• Confirm SMS permission and parsing on the real handset with a small test payment.
• Call live and confirm the payment appears with correct amount and phone metadata.
• Run one successful claim and confirm archive behaviour matches your workflow.
• If webhooks are on: receive a signed test delivery and reject unsigned payloads.
• Replay the same event and confirm your ledger stays idempotent.

5. Production checklist

• HTTPS endpoints only for webhook receivers.
• Rotate integration keys when staff who knew them leave.
• Monitor claim failures and webhook delivery logs from Admin.
• Document escalation when the office phone is replaced or the SIM changes.