Designing an operations-first cross-border payment platform for Nigerian businesses
QPay is a B2B fintech platform focused on helping Nigerian businesses move money across local and international supplier, vendor, and contractor workflows with stronger controls, visibility, and operational reliability.
Dedicated web and admin experiences built around distinct user workflows and permissions.
Central API, ledger, workflow engine, background processing, and observability services.
Approval, compliance, audit, reconciliation, and provider oversight are treated as product primitives.
1. Problem Framing
QPay was designed around a specific business pain: payments are not just a transfer event, they are a workflow problem. Businesses need more than the ability to send money. They need governance, traceability, review surfaces, operational controls, and trust in what happens before and after funds move.
Business Context
Nigerian businesses that pay local and cross-border suppliers often face fragmented systems. Initiation happens in one place, approvals in another, compliance in a manual process, and payment status tracking through back-and-forth messages with finance or operations teams.
QPay addresses that fragmentation by treating payment operations as an end-to-end product system with explicit states, review paths, and financial traceability.
Core Product Goals
- Give business users a clean surface to manage accounts, beneficiaries, KYB, and payments.
- Give internal operators a separate control plane for review, funding, compliance, and observability.
- Ensure financial movements are ledger-backed and auditable.
- Support asynchronous provider workflows, retries, and reconciliation.
North Star
“Make moving money feel controlled, reviewable, and trustworthy, even when the workflow spans approvals, provider callbacks, compliance gates, and background processing.”QPay product direction
2. Product Surface Design
The product has been split into two dedicated frontends because the user-facing workspace and the internal administrative console serve fundamentally different roles.
apps/web
The customer-facing workspace used by businesses to register, complete KYB, manage beneficiaries, view accounts, request FX quotes, create payments, and follow transaction progress.
apps/admin
The internal operations console used by admins, compliance teams, and operators to review KYB submissions, fund accounts, inspect approvals, monitor compliance, and handle operational incidents.
backend
The shared domain layer responsible for auth, accounts, payments, workflow state, observability, notifications, and provider integrations across both apps.
Why the Split Matters
A single frontend became increasingly misaligned with the product as the system gained more internal operational complexity. User tasks and operator tasks diverged in their intent, permissions, urgency, and UI density. Splitting the experience created clearer information architecture, less accidental exposure of internal tools, and better product ergonomics for both audiences.
3. System Architecture
The technical architecture reflects the product model: a shared backend with distinct frontends, plus asynchronous worker-driven processing for durability and operational resilience.
High-Level Architecture
Business user workspace
Internal operations console
Shared domain and workflow layer
Source of truth for ledger and workflow state
Core Technical Building Blocks
- Node.js, Express, and TypeScript backend
- Prisma-backed PostgreSQL data model
- Double-entry ledger design
- Provider adapter layer for external payment providers
- Background outbox worker for deferred execution and retries
- Observability surfaces for health, metrics, and operational review
Request Lifecycle
Business user creates payment intent from the web app.
Approval and compliance checks determine next movement.
Backend or outbox worker handles external provider execution.
Status finalization and operational traceability are recorded.
4. Workflow and Control Model
QPay does not treat payments as a fire-and-forget action. It models the system as a controlled sequence with explicit checkpoints.
Operational Flow
- Business user creates or selects a beneficiary and payout rail.
- User requests an FX quote and confirms a payment.
- Backend evaluates approval policy and compliance conditions.
- If required, the payment enters approval or compliance review queues.
- Once clear, the transaction proceeds toward provider submission.
- Provider attempts, webhook events, and internal audit records preserve the full execution story.
Approval Controls
Threshold-based and policy-based controls prevent unrestricted money movement and add business governance into the workflow.
Compliance Review
Compliance cases and review queues make risk handling visible and operable, rather than burying it in hidden backend logic.
Auditability
Actions across auth, approvals, funding, compliance, and payment flow can be tracked through audit and ledger-aligned records.
5. Reliability, Risk, and Operations
For a fintech product, reliability is not just uptime. It is the ability to reason about what happened, what is stuck, what failed, and what must be retried safely.
| Area | Risk | Mitigation in QPay |
|---|---|---|
| Duplicate execution | Repeated requests or retries can trigger unintended actions. | Idempotency handling, durable workflow state, and controlled provider submission paths reduce replay risk. |
| Asynchronous uncertainty | External provider outcomes do not resolve synchronously. | Webhook ingestion, outbox processing, status history, and reconciliation support visibility over delayed outcomes. |
| Financial inconsistency | Account balances can drift from transaction history without disciplined accounting. | Double-entry ledger structures and balance snapshots create a stronger integrity model. |
| Operational opacity | Internal teams cannot respond quickly without observability. | Health, metrics, audit logs, provider health, and workflow queues provide operational control surfaces. |
Why the Worker Matters
The background worker separates time-sensitive user interaction from retryable provider-side operations. This is important because payment systems often need durable processing beyond the original request cycle. The worker allows the product to maintain responsiveness while still handling retries, transient failures, and delayed external dependencies.
6. Strategic Outcome and Roadmap
QPay has evolved beyond a simple payment demo into a clearer operations-first fintech platform direction. The architecture and product split establish a stronger foundation for future growth.
Current Strategic Strengths
- Clear separation between customer activity and internal operations
- Shared backend platform across multiple product surfaces
- Workflow-first design rather than transfer-first design
- Operational readiness through audit, compliance, and observability primitives
- Extensible provider and reconciliation infrastructure
What This Enables Next
With this base in place, the platform can expand toward more advanced treasury and business-finance capabilities such as multi-currency wallets, invoice-linked payments, scheduled disbursements, bulk payouts, inbound collections, ERP integrations, and more formal role and spend controls.
Provider adapter interfaces, Flutterwave and Paystack webhook verification/readiness work, provider certification checks, and real-provider activation surfaces are already in place.
The upcoming roadmap now shifts toward multi-currency wallets, bulk payouts, scheduled payments, invoice workflows, ERP integrations, vendor portals, treasury tools, spend controls, and inbound collections.