OpenCart

Accept credit and debit cards through the Inovio/Argus Payments gateway on OpenCart 4. The card number never reaches the OpenCart server.

Overview and status

Target is OpenCart 4.1.x, developed and verified against 4.1.0.4 on PHP 8.2. This is the same direct-post architecture proven in the Magento 2 and PrestaShop 9 modules, ported to OpenCart 4, with a handful of deliberate divergences where OpenCart's own conventions are a better fit or where the PrestaShop reference had a behaviour worth not repeating.

Requirements

bcmath is required, not optional. The SDK computes every monetary amount through it so money never passes through a binary float. The settings screen refuses to enable the payment method without it.

Install

The extension ships as a standard OpenCart .ocmod.zip.

Building the package

cd inovio-gateway-opencart
rm -rf build && mkdir build
cp -R upload/. build/
cp install.json build/install.json
cd build && zip -r ../inovio.ocmod.zip . && cd ..

Installing

1. Admin, Extensions, Installer: upload inovio.ocmod.zip, then press Install on the row that appears.
2. Admin, Extensions, Extensions: choose extension type Payments, find Inovio Payment Gateway, press the green + (Install). This step creates the extension's two database tables.
3. Press Edit on the same row, fill in the settings below, set Status to enabled, and Save.

The customer-facing "Saved cards" list appears automatically under My Account, Payment Methods once vaulting is enabled. There is no extra step.

Uninstalling

Uninstalling removes the settings but deliberately leaves the two tables in place. Dropping oc_inovio_order_ref would destroy the gateway PO_ID of every historical order, permanently removing the merchant's ability to refund anything ever taken through the extension. Uninstall and reinstall is also how OpenCart upgrades an extension, so silent data destruction there is indefensible. Drop the tables by hand if you genuinely want the data gone.

Configuration

All settings live at Extensions, Payments, Inovio Payment Gateway, Edit.

Gateway credentials

Until all five required fields are filled in, the extension hides itself at checkout rather than presenting a card form it cannot process.

Payment behaviour settings

Order statuses

Each transition is merchant-configurable. Defaults reference stock OpenCart statuses read from oc_order_status, not guessed.

OpenCart ships Pending, Processing, Failed, Refunded and Voided already, so the extension exposes them as settings instead of adding rows to oc_order_status. This is a deliberate divergence from PrestaShop, which has no unpaid "awaiting capture" or "awaiting 3DS" states and so creates them at install.

Display and availability

Geo Zone, Status, Sort Order and Debug Logging behave as in any OpenCart payment extension. Debug logging writes gateway activity to system/storage/logs/error.log. Card numbers are never logged, because they never reach this server, so there is nothing to redact.

Payment behaviour

Refunds follow the shared settlement-aware contract described in Refunds are settlement-aware. A full refund issues one reverseCapture call with creditOnFail, and the gateway decides between reversing and crediting. A partial refund issues refund and fails loudly with service code 536 if the order has not settled; retry it after settlement.

No silent fallback

There is no catch-and-ignore anywhere in the payment path.

• A 3DS prepare failure is logged loudly, returned to the browser as an error, and the checkout JavaScript refuses to place the order. This is a deliberate divergence from the PrestaShop module, which returned an empty object and let checkout proceed with no 3DS. On an SCA-mandated transaction that produces an unexplained soft decline with nothing in the shop recording why. A merchant who does not want 3DS turns it off in the settings; the extension never decides that at runtime.
• A gateway timeout means the transaction state is genuinely unknown. The extension reconciles via CCSTATUS on the external order id before failing, and never lets the shopper simply retry into a possible double charge.
• Declines surface the gateway's own cardholder-safe advice verbatim. Every other refusal shows a neutral message while the specific reason goes to the log for the operator.
• An order that already carries a status is refused rather than charged again.
• If the settlement state cannot be determined at all, the extension refuses and says so rather than guessing between two money-moving verbs. This is a deliberate divergence from PrestaShop's original isSettled(), which returned false on error and so quietly turned an unknown state into a reversal.

How checkout works on this platform

The direct-post flow

Card fields live in the checkout page's DOM. The browser exchanges them for a single-use TOKEN_GUID by POSTing directly to Inovio's token_service.cfm, and only that token is submitted to OpenCart.

Unlike the PrestaShop module, the extension does not intercept a form submit. It owns its own confirm button and drives the flow with fetch(), replying with a JSON {redirect} or {error}. That is the same contract OpenCart's own cod extension uses. OpenCart hands the whole payment area to the extension, so the form-interception complexity in the PrestaShop build was PrestaShop-specific, not payment-specific.

The order row also already exists before payment runs. OpenCart's checkout/confirm writes the order at status 0 before the payment extension is called, whereas PrestaShop creates it only after approval. This is a better fit: the amount, currency and addresses are frozen on one authoritative record instead of being recomputed from a live cart.

No Inovio-hosted infrastructure is required: there is no hosted payment page and no iframe you have to redirect to.

The PAN-safety property is structural, not a rule operators must remember:

• The card fields in catalog/view/template/payment/inovio.twig have no name attribute and are not inside a form that posts to OpenCart. They cannot be submitted to the shop server even by accident.
• inovio-checkout.js reads them, exchanges them for a token against Inovio directly, and blanks both fields before anything else happens.
• No server-side PHP file in this extension contains the strings card_pan, card_cvv, cardNumber or PMT_NUMB, excluding the SDK's own server-tokenization helper, which this extension does not call.
• The vault table stores gateway references (CUST_ID, PMT_ID) plus brand, last four and expiry, which are display-only fields. There is no column that could hold a PAN or CVV.

This was verified, not assumed: a full database dump taken after a live test run contains zero occurrences of the test card number.

The signature endpoint is a minting oracle

extension/inovio/payment/inovio.signature mints HMACs on demand. Left open, it would let anyone tokenize cards against the merchant's site, which is card testing. It enforces three checks:

1. Session-bound. session.data['payment_method']['code'] must be inovio.inovio. OpenCart has no per-form CSRF token on the storefront (the customer_token in account URLs does not exist during checkout), so the session's own checkout state is the binding. A cross-site attacker cannot set it.
2. Cart-bound. The session must hold a non-empty cart.
3. Rate-limited. Twelve signatures per 60 seconds per session.

Every refusal is logged with its reason. A silent 403 here would mean the browser cannot tokenize and the shopper sees an unexplained failure.

3-D Secure

For the two-token mechanics, see Two-token 3D Secure. Token B is persisted to oc_inovio_order_ref at the moment the order is parked, because the ACS return arrives on a separate request that has no access to the original POST.

Securing the ACS return. The ACS POSTs the challenge outcome cross-site, and it may arrive with no session cookie, so the return leg cannot rely on session state. It is bound to a legitimate order by the order id on the return URL and by a constant-time comparison of the ACS TransactionId against the procTransId stored at enrollment. The second is what makes the first safe: an order id is a guessable integer, but the procTransId is not, and only the real ACS knows it. A replay guard additionally refuses any order that has already left the awaiting-3DS status.

Admin operations

Capture, void and refund are driven from the extension's own panel on the order screen, rendered by admin/view/template/payment/inovio_order.twig.

Order history is written directly by the panel rather than through addHistory(). The admin sale/order model has no addHistory() at all; only the catalog model does, and OpenCart's own admin reaches it by spinning up a second store instance and proxying to the api/order route, which requires a configured API user and fails without one. Worse, the catalog method re-runs anti-fraud extensions, subtracts stock and redeems coupons on a transition into a processing status, all of which are wrong to re-run when capturing or refunding an order that already completed checkout. The panel writes the history row and status itself: exactly the two intended effects, nothing else.

Saved cards

OpenCart 4.1.0.4 has no native payment-token API. It does ship catalog/controller/account/payment_method.php, but that only asks each enabled payment extension for a rendered HTML fragment (extension/<ext>/account/<code>). There is no storage, schema or CRUD behind it, and a stock install has no oc_customer_payment* table of any kind. So the extension owns oc_inovio_stored_card and renders into that native hook, which is strictly better wiring than PrestaShop's displayCustomerAccount.

The ownership (IDOR) guard is mandatory and explicit. Stored-card ids are small integers that appear in form posts, so guessing another shopper's id is trivial. Every lookup or charge goes through Vault::findForCustomer(), which requires customer_id to match the logged-in session as a checked condition, and re-asserts it on the returned row so a future SQL edit cannot quietly drop it. "Row does not exist" and "row is not yours" are answered identically, so the endpoint cannot be used as an oracle for which ids are live.

Deleting a saved card removes the local row only. Whether it should also revoke the gateway-side PMT_ID is an open question against Inovio's customer API; behaviour is kept identical to the PrestaShop module rather than invented here.

Known gaps

• Only en-gb translations ship. Other languages fall back to OpenCart's default behaviour for a missing language file.
• Multi-store installs were not tested. The vault is keyed on customer_id only, with no store_id column. PrestaShop's equivalent carries id_shop.
• Apache access and error logs could not be scanned for the PAN. docker exec hung reliably on those files in the test environment. docker logs, the same streams, was scanned and returned zero. A PAN could never appear in a request URL in any case, since the only request that carries it is a POST body sent to Inovio, not to OpenCart.
• Whether deleting a saved card should revoke the gateway-side PMT_ID is open.

Verified end to end

A Playwright suite lives in e2e/, covering seven spec files and ten tests.

Divergences from the PrestaShop reference

Troubleshooting

Source

Repository: Inoviopay/inovio-gateway-opencart (private, available from Inovio).

Extension code inovio, packaged as inovio.ocmod.zip, installed to extension/inovio/.

upload/
  admin/
    controller/payment/inovio.php     settings, install/uninstall, capture/void/refund
    language/en-gb/payment/inovio.php
    view/template/payment/inovio.twig        settings screen
    view/template/payment/inovio_order.twig  order-screen panel
  catalog/
    controller/payment/inovio.php     index/signature/threeds/confirm/threedsReturn
    controller/account/inovio.php     "Saved cards" UI + delete
    model/payment/inovio.php          offers the method to checkout
    view/template/payment/inovio.twig card form
    view/javascript/inovio-checkout.js direct-post + 3DS client
  system/
    library/gateway.php               gateway service (verbs, refs, request building)
    library/vault.php                 saved-card storage + IDOR guard
    vendor/inovio/                    vendored PHP SDK + classmap autoloader
install.json

File placement is load-bearing

Both startup controllers register Opencart\System\Library\Extension\<Extension> to extension/<code>/system/library/, and OpenCart's autoloader then appends only the class tail after that namespace. So Opencart\System\Library\Extension\Inovio\Gateway resolves to extension/inovio/system/library/gateway.php. There is no second inovio/ directory beneath system/library/.

This build originally shipped the files at system/library/inovio/gateway.php, which looks natural and is wrong. The failure mode is nasty: everything appears fine until the moment you press Install, which dies with Class "Opencart\System\Library\Extension\Inovio\Gateway" not found, after the oc_extension row has already been written but before the schema is created.

The vendored SDK

system/vendor/inovio/gateway-sdk/ is a verbatim copy of the Inovio PHP SDK, loaded by a small classmap autoloader at system/vendor/inovio/autoload.php. It is vendored rather than Composer-required because the package is not on Packagist, and an OpenCart extension installs as a self-contained zip through the admin UI with no Composer step in that path. The SDK has zero Composer dependencies, which makes this clean.

The autoloader indexes by file content, not by filename, for two reasons. OpenCart's own autoloader lower-cases and snake-cases class tails, so ResultMapper would be looked for at result_mapper.php; and the SDK's files are not one-to-one with class names anyway, since Result.php declares about a dozen classes. Neither OpenCart's convention nor PSR-4 can resolve it.