Integrations and M-PESA¶

Integration surface¶

TruConnect — local scale protocol bridge (serial, TCP, UDP, HTTP).
Pesaflow / eCitizen — invoice push, STK push, payment callbacks, reconciliation webhook.
NTSA, KeNHA — vehicle and driver reference lookups.

Payment flow¶

Operator opens a prosecution invoice in the frontend and triggers settlement.
Backend posts the invoice to Pesaflow at pesaflow.ecitizen.go.ke/PaymentAPI/iframev2.1.php with a secure hash computed per the Pesaflow integration guide.
Pesaflow returns a checkout URL; the frontend opens it in a dialog.
Payer authorises the STK push on their phone.
Pesaflow posts back to api/v1/payments/callback/{success,failure,timeout} on the backend.
The backend marks the invoice paid, generates a receipt, and kicks the case workflow forward.
A reconciliation job polls api/v1/payments/webhook/ecitizen-pesaflow for drift and retries idempotently.

sequenceDiagram
  participant UI as Frontend
  participant BE as truload-backend
  participant PF as Pesaflow
  participant P as Payer
  UI->>BE: settle invoice
  BE->>PF: push invoice (secure hash)
  PF-->>UI: checkout URL (iframe)
  UI->>P: STK push
  P-->>PF: authorise
  PF->>BE: callback success/failure/timeout
  BE->>BE: generate receipt, advance case
  BE->>PF: reconciliation poll (idempotent)

Code entry points¶

Concern	File
Outbound invoice push	`Services/Implementations/Financial/ECitizenService.cs`
Callback handlers	`Controllers/Financial/PaymentCallbackController.cs`
Reconciliation webhook	`Controllers/Financial/PaymentController.cs`
Frontend checkout dialog	`truload-frontend/src/components/payments/PesaflowCheckoutDialog.tsx`
Frontend queries	`truload-frontend/src/hooks/queries/useIntegrationQueries.ts`

Test suites¶

Suite	Purpose
`pesaflow_api_test.py`	OAuth, invoice creation via iframe, payment status — direct against Pesaflow
`pesaflow_invoice_e2e.py`	Backend-mediated: login, select unpaid invoice, push, poll status
`pesaflow_callback_reconciliation_e2e.py`	Callback success/failure/timeout + webhook idempotency