infifni/sylius-netopia-plugin

Sylius integration with NETOPIA Payments (netopia-payments.com) - hosted card payments via the v2 API (payment/card/start), JWT-verified IPN, payment status sync.

dev-main / 0.1.x-dev 2026-08-24 21:15 UTC

Requires

• php: ^8.3
• sylius/sylius: ^2.2
• symfony/framework-bundle: ^7.4
• symfony/http-client: ^7.4

Requires (Dev)

• phpunit/phpunit: ^11.0
• symfony/config: ^7.4
• symfony/dependency-injection: ^7.4
• symfony/phpunit-bridge: ^7.4

proprietary

Published on Packagist.org on 2026-08-24 21:24 UTC

README

Integrates NETOPIA Payments (Romanian card payment processor) into Sylius 2.2+ as a Payum gateway, using the v2 Payment API.

How it works

• Hosted payment page - the start request is sent with payment.instrument = null, so the customer types the card data on NETOPIA's secure page (paymentURL from the response). The shop never touches card data, so no PCI DSS burden.
• Return flow - NETOPIA redirects the customer back to the Payum capture URL; the plugin refreshes the payment status via operation/status and Sylius continues to the thank-you page.
• IPN - NETOPIA POSTs the final status to a per-payment payum_notify_do URL. The Verification-Token JWT (RS512) is verified against the NETOPIA public key (issuer, audience = POS signature, payload SHA-512 hash) before the status is trusted. A paid/confirmed IPN completes the Sylius payment, which marks the order as paid - the standard Sylius flow continues (confirmation e-mail, shipment, etc.). No invoice is emitted - the plugin does not integrate any invoicing.

Configuration

Environment variables (see Configuration.php - every plugin config param defaults to one of these):

NETOPIA_POS_SIGNATURE=XXXX-XXXX-XXXX-XXXX-XXXX
NETOPIA_API_KEY=your-api-key
# PEM string, base64-encoded PEM, or absolute path to the .pem/.cer file:
NETOPIA_PUBLIC_KEY=/path/to/netopia-public.cer
NETOPIA_PRIVATE_KEY=            # unused by the v2 card flow, reserved
NETOPIA_LIVE=0                  # 0 = sandbox, 1 = production

The same values can be overridden per payment method in Admin → Payment methods → gateway configuration; empty admin fields fall back to the env vars.

Installation (path repository)

"repositories": [
    { "type": "path", "url": "../sylius-netopia-plugin" }
]

composer require infifni/sylius-netopia-plugin:*@dev

Register the bundle in config/bundles.php:

Infifni\SyliusNetopiaPlugin\SyliusNetopiaPlugin::class => ['all' => true],

Create the payment method (makes it the only enabled one; add --keep-others to keep existing methods enabled):

php bin/console infifni:netopia:install

Notes

• Payment retries create a new Sylius payment, and the NETOPIA orderID is {orderNumber}-{paymentId}, so error 56 (duplicated orderID) cannot occur.
• The IPN endpoint answers NETOPIA's expected JSON ({"errorType":0}), and replies 400 on any verification failure so NETOPIA retries later.
• Sandbox host: secure-sandbox.netopia-payments.com; live: secure.netopia-payments.com/api (same URLs as the official SDK).