ECG Payment & Recharge
Orchestrator

Platform Overview

The platform exposes a vendor-facing REST API and orchestrates multi-step payment workflows via Wolverine sagas backed by Marten/PostgreSQL and RabbitMQ. Sagas provide durable, compensatable workflows — if any step fails, the saga can roll back or retry safely without duplicating side-effects.

Services

The platform is decomposed into six microservices. Api.Gateway is the only publicly accessible service; all others communicate internally via durable RabbitMQ messaging.

System Architecture

The gateway is the only publicly reachable service. All mutation operations are dispatched to the orchestrator via RabbitMQ commands, which then fans out to the appropriate leaf services. Read-heavy endpoints are served directly from the gateway using a two-tier Redis cache.

1 Prepaid Meter Vending

Accepts a vend request from a vendor, validates it against the pre-transaction guard chain, then dispatches a VendPrepaidSaga. The saga transfers funds from the vendor's Fineract float account to the meter wallet, calls the correct meter vendor API to generate an electricity token, and delivers an SMS to the customer plus a webhook callback to the vendor.

2 Postpaid Meter Vending

Extends the vend flow for postpaid meters. Before any funds are moved, the VendPostpaidSaga first queries the SUBS Postpaid API to validate the meter and retrieve the outstanding bill. After payment is complete, a postpaid bill credit is recorded and postpaid-specific notifications are sent, followed by an additional GL entry for the notification cost.

Same endpoint as prepaid — routing is determined by the meter's category code.

3 Vend Status Lookup

Allows a vendor to query the outcome of a previously submitted vend using either the platform's internal reference or the vendor's own external reference. Returns the generated electricity token if vending succeeded. The endpoint response is output-cached per reference in Redis.

4 Multi-Vendor Meter Recharge Routing

Routes token generation requests to the correct meter vendor API based on the meter's MeterCategoryCode. Each vendor has dedicated credentials, endpoint logic, and a failure count that is tracked and surfaced to detect service degradation.

On repeated failures, the MeterCategoryFailureTrackingHandler increments the category's failure count, which is exposed through the meter category status endpoint for vendor visibility.

5 Meter Category Status Query

Returns the meter categories assigned to the authenticated vendor, along with the active or inactive status of each. This allows vendors to know in real time which meter types are available for vending. Responses are output-cached per vendor with a 2-minute TTL backed by Redis.

6 Transaction Reversal Ticketing

Vendors can raise a formal reversal ticket against a completed vend transaction. The ticket carries a typed reason, a description, and a status lifecycle managed by the platform. When an admin approves the ticket, a MeterVendReversalSaga executes a Fineract fund refund and GL correction. Vendors can also query existing tickets by transaction reference.

7 Vendor Balance Enquiry

Returns the authenticated vendor's current available float balance, total Fineract account balance, account currency, and account status. Because balance data is fetched live from Fineract during the VendorChecker preprocessor and placed into the per-request state bag, no additional database round-trip is needed at the endpoint itself.

8 Vendor Top-Up

Processes a vendor float account top-up initiated by an external payment (mobile money or bank transfer). The TopupSaga tracks both the base Amount and the commission-inclusive TotalAmount separately — the total is deposited into Fineract while the commission split is recorded in the GL entry. A top-up invoice PDF is generated and delivered by email and webhook.

9 Vendor Settlement

Moves funds from a vendor's Fineract float account to an external bank or mobile money account on a vendor-configured daily schedule. The BillingCronJobs runs an hourly TickerQ cron job (0 0 * * * *) that finds all vendors whose configured SettlementTime falls within the current ±5-minute window and triggers a settlement saga for each.

10 Invoice Lifecycle Management

Manages the complete lifecycle of vendor invoices from creation through to verified payment or rejection. Every state change produces an audit entry. Two mark-as-paid modes are supported: a basic confirmation and an enhanced version (V2) that accepts proof-of-payment file attachments. On verification, a receipt PDF is generated and delivered; on rejection, a rejection notification is sent.

Invoice types: settlement and topup. Email templates: invoice.html, payment-received.html, payment-rejected.html.

11 Document Generation (PDF & Screenshots)

Renders HTML templates or arbitrary HTML strings into PDF documents or screenshots using a headless browser. Output files are uploaded to Azure Blob Storage and the resulting URL is returned to the caller for storage or delivery.

12 Multi-Channel Notifications

Delivers notifications via SMS, email (direct and template-based), and HTTP webhook callbacks. Supports both individual and bulk delivery modes. All channels are driven by dedicated RabbitMQ queues with Wolverine durable inbox/outbox guarantees, ensuring at-least-once delivery even across service restarts.

13 Vendor Authentication & Authorization

Dual-mode authentication at the gateway. API key authentication validates the key against an internal Auth API and issues a JWT bearing a VendorId claim. OAuth2/OIDC via Keycloak is also supported for JWT introspection.

Every protected endpoint runs the VendorChecker preprocessor, which hydrates the vendor's Fineract balance, status, business rules, and meter categories into a per-request state bag using a two-tier hybrid cache: a 10-second in-memory layer backed by a 20-second Redis layer. This eliminates per-request database round-trips while keeping data fresh.

14 Pre-Transaction Guard Chain

A sequenced pipeline of preprocessors executes before any vend or mutation endpoint. If any guard fails, a standardised error response is returned immediately — the handler is never reached. Guards run in order and each receives the full hydrated vendor state bag from the VendorChecker.

15 Idempotency & Output Caching

Prevents duplicate mutations and avoids redundant computation on reads. Mutation endpoints that accept an x-idempotency-key header will replay the original response from Redis for any duplicate request within the configured window — the handler is never re-executed. Read endpoints use FastEndpoints output caching with per-vendor or per-reference cache keys backed by Redis.

16 Meter Lookup (Prepaid & Postpaid)

Resolves meter details before or during a vend, using different paths depending on meter type:

• Prepaid — Performed at the gateway via the SUBS Enterprise API using HMAC-SHA256 signed requests, before dispatching the vend command to the orchestrator.
• Postpaid — Performed inside the orchestrator saga as Step 1 of VendPostpaidSaga, via the SUBS Postpaid API, to validate the meter and retrieve the outstanding bill before any funds are moved.

Service Responsibility Matrix

Which services are involved in each feature.