Financial Operating Layer for E-commerce: CRM ↔ Nova Poshta ↔ NovaPay
A custom financial operating layer that unifies CRM, Nova Poshta and NovaPay into a single source of truth: nightly registry reconciliation, precise commission accounting, and closing on delivery fact. An enterprise solution on your own infrastructure.
// Technologies
What it is
A custom «financial operating layer» that unifies CRM, Nova Poshta and NovaPay into a single source of truth for cash-on-delivery (COD) e-commerce. It eliminates manual reconciliation and hidden financial losses, and deploys on your own infrastructure (Docker) — it is your asset, not yet another subscription.
The problem: the hidden losses of COD
- Time — 100+ waybills are checked by hand every day; the accountant’s registry reconciliation takes 2–3 days.
- Money — the floating NovaPay commission (2% + 20 UAH) is counted «approximately», creating an invisible cash gap.
- Data — sales are closed «blindly», which breaks marketing ROI calculations.
The solution: a single source of truth
A Core Orchestrator becomes the single hub between CRM, Nova Poshta and NovaPay. Every night the system parses NovaPay registries and matches them to orders by a cross-key: waybill number (Column 9), the exact withheld commission (Column 5) and operation_uid (Column 13). The unique operation_uid guarantees 100% idempotency — absolute protection from double commission charges. Deals close strictly by StatusCode 9 (the parcel was actually received), not by the card-payment fact — so there is no fraud risk and the sales data stays clean.
Before / after: the transformation matrix
Process | Before: manual process | After: our framework |
|---|---|---|
Tracking | A manager checks waybills by hand | Auto status updates (Polling + Webhooks) |
Reconciliation | Excel sheets over 2–3 days | Daily nightly parsing of NovaPay registries |
Closing | By card-payment fact (fraud risk) | Strictly by StatusCode 9 (received fact) |
Commission | Approximate cost estimate | Exact sum from Column 5 of the NovaPay registry |
The economics of implementation
Based on 200 COD orders per day (1–3M UAH monthly turnover):
- 2–3 FTE — staff optimization: accountants and managers are freed from routine for analytics.
- 15–30k UAH/mo — direct savings from catching discrepancies and accurate commission accounting.
- 100% — marketing transparency: a sale is recorded strictly on the delivery fact (Status 9).
Architecture and reliability
Event-Driven core. The system is built on events (e.g. ParcelDelivered), so custom listeners are easy to add without touching the core. Stack: PHP, PostgreSQL, Redis, Docker.
Security. Secrets are stored outside the repository; auto-rotation of the Refresh Token and generation of x-sign headers (RSA SHA-256) for NovaPay.
Resilience. Redis queues and protection from Nova Poshta API timeouts via Exponential Backoff Retries.
Exception handling. An Unmatched UI to link lost payments in a few clicks, a full audit log of every API request, and Force Close for manual control of critical operations.
Dry-Run mode. APP_DRY_RUN=true runs the full cycle on real data without writing to the CRM — you see the financial result and matching accuracy before going live.
Multi-entity. A flexible merchant_profiles table (separate Nova Poshta, NovaPay and CRM keys per merchant) and smart routing of payments across settlement accounts (IBAN).
Subscription vs your own asset
Criterion | Mass subscription (SaaS) | Your own asset |
|---|---|---|
Infrastructure | Someone else’s infrastructure | Your servers (Docker), full control |
Limits | Hard limits | No artificial restrictions |
Payment | Subscription fee | One-time core development |
Customization | Limited | Deep, tailored to your processes |
Data | At the provider | Fully yours |
Integration and scaling
The framework is written through abstract interfaces (CrmAdapterInterface). The base MVP includes a ready SalesDrive integration, while the adapter layer lets you connect KeyCRM, KeepinCRM, 1C/BAS or any custom system in days. Deploying the base core takes about 15 minutes via docker-compose.
Roadmap
- BI & Analytics — dashboards of buyout rate by region and logistics branch.
- Returns management — automatic reverse-waybill generation and return-commission accounting.
- ML scoring — predictive buyout-risk assessment from client history to request prepayment preventively.
“The problem is not a lack of plugins, but the lack of a single source of truth.”