Nova Poshta Premium — a Nova Poshta module for OpenCart 2.3, 3.x and 4.x

Nova Poshta Premium is a module for OpenCart 2.3, 3.x and 4.x that connects your store to Nova Poshta in 10 minutes. The customer picks a city and branch right in the cart, and the waybill is created automatically when the order moves to the status you chose in the settings (for example, “Processing”). No third-party iframes, no rewriting the checkout, no daily copying of data into the Nova Poshta account.

How it works, step by step

1. The customer on the site chooses Nova Poshta as the shipping method, searches for a city, and picks a branch.
2. The order is created in your OC admin panel with the chosen branch saved against it.
3. You move the order to the trigger status chosen in the module settings under “Create TTN when order status changes to” (for example, “Processing”; until a status is chosen, no waybill is created automatically).
4. The module automatically calls the Nova Poshta API: it creates the recipient as a private individual (from your checkout — name and phone), then prints the waybill. The number is written to the order.
5. With Premium: it polls Nova Poshta hourly for the status of every active shipment, gets the payout number for cash-on-delivery orders, and sends a webhook to your CRM/ERP on every status change.

Under the hood

• When the Nova Poshta API stops answering, your store keeps selling: cities and branches come from the saved directory, the price is Nova Poshta’s last tariff, and waybills are queued and created automatically once the API is back. On a test stand with a hung API, checkout took 46 s before this update and about 1 s after it (up to 7 s for the first buyer at the start of an outage).
• Native for OpenCart 4.x — PSR-4 namespaces, the events API, Twig. Not OCMOD, not XML mods. Compatible with future OC releases with no rewrite.
• The API key is encrypted in the database — AES-256-CBC with an HMAC check, using an encryption key derived from the store’s install path and database name. The licence key is encrypted the same way. If someone dumps the database, the key can’t be read in plain text.
• A city and branch cache with lazy refresh — a full weekly sync via cron, lazy loading of branches for requested cities (7-day TTL). Autocomplete in the checkout responds in 44 ms instead of 211 ms for a direct API call.
• A two-stage waybill creation: first Counterparty.save for the recipient (a PrivatePerson with a phone number in Nova Poshta’s format), then InternetDocument.save. Works for every sender type — private individual, sole proprietor, LLC.
• HMAC-signed webhooks with retries: 5/10/20/40 min exponential backoff, up to 4 attempts. sha256 signatures, an X-NP-Signature header.

How to install

1. Download nova_poshta_premium.ocmod.zip via Extensions → Installer in your OC admin panel. For OpenCart 3.0.x, use the nova-poshta-premium-oc3-1.3.14.ocmod.zip build (available in the product’s downloads); for OpenCart 2.3, use nova-poshta-premium-oc2-1.3.11.ocmod.zip.
2. Activate it in the list, then open the settings → click “Complete installation” (this creates the database tables, events and cron tasks).
3. Paste in the API key from your Nova Poshta account, click “Test connection” — you’ll see “Connection working”.
4. Choose your city and branch → load the sender profile → save.
5. Done — a block for choosing Nova Poshta delivery appears in the cart.
6. For Premium features: paste in the licence key from the e-mail after payment → “Activate licence”.