PrestaShop

Tokenized direct-post card checkout for PrestaShop 9, on the Inovio gateway. The card number never reaches the shop server.

Overview and status

This is the reference implementation of the four. The other three plugins were ported from it, and the design document behind it is the shared design rationale for all of them.

PrestaShop gives the least framework of the four platforms. It has no native payment-token or vault API, no platform concept of authorize versus capture, no pending-authentication order state, and no order-submission JavaScript event. Each of those is a verified absence against official PrestaShop 9 documentation, not an assumption, and each is a thing this module builds itself. The module creates its own saved-card table and its own two order states (awaiting capture, awaiting 3-D Secure) at install time.

Requirements

bcmath is required, not optional. The SDK's Money type does every decimal calculation through it so amounts never touch a binary float. Installation fails without it.

PrestaShop 8.x is not supported. 8.0 through 8.2 supports PHP 7.2.5 through 8.1 and no higher, while 9.x requires 8.1+ and supports through 8.5. The two lines overlap at exactly PHP 8.1 and PrestaShop maintains separate documentation branches for them, so supporting both would mean runtime version shims or two builds. PrestaShop 1.7 is end of life as of the 9.0 release.

Install

Copy the inoviopayment/ directory into your shop's modules/ directory, or upload the ZIP through Modules, Module Manager, Upload a module. Then install it.

Configure it under Payment, Payment Methods, Inovio Payment Gateway, Configure.

Installation creates the module's own saved-card table and the two order states it needs.

php bin/console prestashop:module install inoviopayment

Modules -> Module Manager -> search "Inovio" -> Install

Configuration

All settings are on the module's Configure screen.

Gateway credentials

Site Key is a separate per-site HMAC secret issued by Inovio support. It is not the API password, and it is not something you can generate. It is used only to sign the browser's tokenization request. Without it the browser cannot tokenize and checkout fails with error 121.

Gateway Product ID (LI_PROD_ID) is a product registered on the gateway, not a product or SKU from your catalogue. The whole order bills as one line item under it.

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

Payment behaviour settings

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. The merchant gets one Refund control and is never asked to guess at the settlement state, because they have no way to know it.

Refunds are driven from PrestaShop's actionOrderSlipAdd hook. All three of PrestaShop 9's refund flows go through OrderSlipCreator, which fires that hook once per operation with the created slip; the amount is total_products_tax_incl + total_shipping_tax_incl. The TransactionResult is consumed, so a declined refund throws rather than producing a credit slip that tells the customer they were refunded.

A gateway timeout means the transaction state is genuinely unknown. The module reconciles via status() before failing an order, including on the 3-D Secure completion leg. A non-challenge PENDING response is parked in a pending state with the references recorded, not treated as a decline, because the gateway may still settle it.

How checkout works on this platform

The direct-post flow

Card fields live in the checkout page's DOM, inside the embedded PaymentOption form. The shipped JavaScript reads them, requests an HMAC signature from the module's signature front controller, exchanges the PAN for a single-use TOKEN_GUID by POSTing directly to Inovio, and only that token is submitted to PrestaShop. Nothing in the payment path on your server ever sees a card number.

The card fields carry no name attribute, so a JavaScript failure cannot POST the PAN to the shop server by accident.

Because PrestaShop has no order-submission JavaScript event, the module intercepts the payment form's own submit event and re-submits it once tokenization completes. This is undocumented but standard practice across PrestaShop payment modules.

What reaches the PrestaShop server is the whole payload and nothing else: token_guid, token_guid_completion (3DS only), pmt_expiry, cc_brand, cc_last4, and the 3DS ddc_reference_id and browser data. The CVV is never in that list. It goes browser-direct to the token service alongside the PAN and is stored nowhere, by anyone.

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

Saved cards store the gateway's own references (CUST_ID, PMT_ID) plus the card brand, last four digits 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 mysqldump of the shop database taken after a live test run contains zero occurrences of the test card number in any representation. ps_order_payment.card_number holds the last four digits only.

The signature endpoint

controllers/front/signature.php mints HMACs on demand. Left open it would let anyone tokenize cards against the merchant's site, so it is CSRF-protected with a per-visitor random nonce, cart-bound, and rate-limited with a server-side database-backed counter. The 3DS prepare endpoint is rate-limited too, because every hit there is a paid gateway call.

3-D Secure

The module creates its own "awaiting 3-D Secure" order state at install, because PrestaShop has no pending-authentication state and no equivalent state machine. The order is parked there during the challenge and exited by an explicit OrderHistory transition. The ACS return arrives at the threedsreturn front controller, which is CSRF-exempt and authenticated by TransactionId instead.

For the two-token mechanics, see Two-token 3D Secure.

Admin operations

PrestaShop has no documented admin hook for a merchant-triggered capture, so the module owns its own back-office controls for capture and void, alongside the two order states it created at install.

Saved cards

PrestaShop has no native payment-token or vault API. Core ships ps_order_payment.card_number, card_brand, card_expiration and card_holder columns, but there is no storage, encryption, UI or API behind them, and no official example module demonstrates vaulting. This is what real modules do: PayPlug, SIBS and Axerve all ship one-click this way.

So the module owns an inovio_stored_card table (an ObjectModel) plus a storedcards front controller for the customer-account UI, surfaced through the displayCustomerAccount hook. Rows hold the gateway's CUST_ID and PMT_ID references plus brand, last four and expiry.

The save-card opt-in is persisted on the order reference and restored after the ACS return, so it is not dropped across a 3-D Secure challenge.

Deleting a saved card removes the local row.

Known gaps

• The checkout JavaScript has not been exercised in a real browser as part of the module's own developer tests. Because PrestaShop has no order-submission event, the script intercepts the form's native submit, and that path needs a browser pass plus a theme-compatibility matrix. The Playwright suite does drive a real browser through checkout; the gap is systematic theme coverage.
• 3DS challenge completion needs a browser and an HTTPS-reachable return URL. Test 3-D Secure on an HTTPS-reachable host.
• Whether deleting a saved card should also revoke the gateway-side payment method is open (design document §11). Behaviour is currently local-row-only, and the OpenCart extension deliberately matches it rather than inventing different behaviour.

Verified end to end

An 18-spec Playwright suite lives in e2e/, with a local stack at stack/prestashop/docker-compose.yml.

Spec 14 is the regression guard for the money-losing bug this design eliminated: the old code would have silently reversed the entire order total in phase A. Settlement is simulated gateway-side because settlement is an acquirer batch process with no UI anywhere, so it fakes the acquirer, not the shop.

There are also CLI developer scripts under tests/, which need a booted Symfony kernel and so run through a small runner: e2e_module.php (sale, order, vault, refund through module code), e2e_module_verbs.php (authorize, capture, void, partial capture, saved card) and sdk_verbs.php (raw SDK verbs, deliberately exercising the 536 path). They are CLI-only, guarded so they are not web-reachable.

Troubleshooting

Source

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

Module technical name inoviopayment, installed to modules/inoviopayment/.

inoviopayment.php              main class (PaymentModule)
classes/
  InovioGateway.php            SDK requests + transaction verbs
  InovioStoredCard.php         vault ObjectModel
  InovioVault.php              vault write path
controllers/front/
  signature.php                HMAC for browser tokenization
  validation.php               order placement
  threeds.php                  3DS prepare (AJAX)
  threedsreturn.php            ACS return
  storedcards.php              saved-cards management
views/js/inovio-checkout.js    direct-post + 3DS checkout JS
vendor/inovio/gateway-sdk/     vendored SDK

The SDK is vendored rather than Composer-required because it is not on Packagist and PrestaShop Addons requires a self-contained single-module ZIP. The SDK has zero Composer dependencies, which makes this clean.