Download the PHP package birkof/netopia-mobilpay-bundle without Composer

Netopia MobilPay Bundle — Architecture Overview

A thin, typed Symfony integration layer over the birkof/netopia-mobilpay low-level SDK. It wires the SDK into the Symfony service container and exposes two responsibilities of the Netopia (MobilPay) card-payment protocol:

• Outbound — build an RSA‑encrypted payment request to redirect a customer to the gateway.
• Inbound — decrypt and authenticate the gateway's IPN (Instant Payment Notification) callback and produce the <crc> acknowledgement it expects.

The bundle holds no state, no persistence, and no HTTP controllers. It builds request objects and parses notifications; the consuming application owns routing, fulfilment, and storage.

Source of truth for this document: the files under src/ (14 PHP files, ~1090 LOC), composer.json, phpunit.xml.dist, and .github/workflows/ci.yml. Usage examples live in src/Resources/doc/index.md.

Requirements

From composer.json:

Autoload (PSR‑4): birkof\NetopiaMobilPay\ → src/.

Installation

1. Require the package

2. Register the bundle

With Symfony Flex this is automatic. Otherwise add it to config/bundles.php:

3. Configure the gateway

signature is required — the bundle fails to boot without it. payment_url, public_cert and private_key are optional (defaults: sandbox URL, null, null). Both public_cert and private_key accept either a file path (resolved relative to %kernel.project_dir%) or the inline PEM content.

4. Define the confirm and return routes

The bundle generates absolute URLs from two route names it expects you to define (NetopiaMobilPayConfiguration::CONFIRM_URL / ::RETURN_URL). These names are mandatory — missing them breaks URL generation at container build time:

Usage

Both entry points are autowired by their interface:

Start a payment (outbound)

createCreditCardPaymentObject() validates the input, builds and RSA‑seals the request, and returns the SDK request object exposing the sealed env_key / data (and cipher / iv for block ciphers). Render an auto‑submitting form that POSTs them to the gateway URL.

PCI note: leave the creditCard argument empty and let the gateway's hosted page collect the card details. Passing a raw PAN/CVV through your server places the whole application in PCI‑DSS SAQ‑D scope.

Handle the confirmation (inbound IPN)

Netopia POSTs the encrypted notification to your netopia_mobilpay_confirm_url route. Decrypt it, verify the amount/order yourself, then acknowledge with <crc>:

IpnResult predicates: isConfirmed(), isPaid(), isPending(), isCanceled(), isError(). See src/Resources/doc/index.md for the full integration guide.

Architecture at a glance

The SDK does the cryptography and XML; this bundle adapts it to Symfony DI and gives the inbound side a typed, vendor‑agnostic result.

Components

Grouped by directory under src/:

Bundle + DI

Service graph built by the extension:

Resources/config/services.yaml aliases each interface to its service for autowiring: NetopiaMobilPayServiceInterface → netopia_mobilpay.payment, NetopiaMobilPayIpnHandlerInterface → netopia_mobilpay.ipn_handler.

Configuration value object

Configuration/NetopiaMobilPayConfiguration.php — runtime holder for the gateway settings, built once and shared by both services.

• Reads public_cert / private_key as either a file path (resolved under %kernel.project_dir%) or the literal PEM content (setPublicCert/setPrivateKey fall back to the raw value when it is not a readable file).
• In its constructor it generates the absolute confirm and return URLs via the router from two route names it expects the application to define:
  • netopia_mobilpay_confirm_url (const CONFIRM_URL)
  • netopia_mobilpay_return_url (const RETURN_URL)
• resolvePaymentUrl(bool $useTokenEndpoint) derives the per‑request endpoint from an immutable base URL: the base for a normal payment, base + '/card4' for a token payment. The base is never mutated, so repeated/token calls cannot accumulate /card4 or leak across requests on long‑running workers.
• Currency constants: CURRENCY_RON, CURRENCY_EUR, CURRENCY_USD.

Outbound — payment request building

Service/NetopiaMobilPayServiceInterface.php + NetopiaMobilPayService.php.

• createCreditCardPaymentObject($orderId, $amount, $currency, $details, $billingAddress, $shippingAddress, $creditCard, $extraParameters):
  1. validates orderId (non‑empty), amount (positive numeric) and currency (one of the CURRENCY_* constants) before the try/catch, so a specific input error is not masked;
  2. builds a Mobilpay\Payment\Request\Card — signature, confirmUrl, returnUrl, a Mobilpay\Payment\Invoice (currency/amount/details), optional billing/shipping Mobilpay\Payment\Address, optional Mobilpay\Payment\Instrument\Card, and token extraParameters;
  3. resolves the payment URL for the request;
  4. calls ->encrypt($publicCert) (RSA envelope) and returns the request object.
• createSmsPaymentObject($orderId, $serviceId) — the SMS‑payment equivalent.
• composeAddressObject() sets only the fields the SDK's Address actually serializes (type, firstName, lastName, address, email, mobilePhone).
• composeCreditCardObject() builds a raw‑PAN CardInstrument. Its docblock warns that this server‑side card path places the application in PCI‑DSS SAQ‑D scope; the hosted payment page (leave $creditCard empty) is the recommended flow.

The returned request object exposes the sealed env_key / data; the application renders an auto‑submitting HTML form POSTing them to getPaymentUrl().

Inbound — IPN handling (src/Notification/)

Errors

Exception/NetopiaMobilPayException.php — the single extends \Exception type thrown by the bundle (invalid input, failed encryption, failed/empty/garbage IPN payload).

All src/ classes declare declare(strict_types=1).

Request / response flows

Outbound (start a payment):

Inbound (gateway confirmation / IPN):

Security model

• Authenticity is the RSA envelope. Netopia seals the IPN against your public certificate; only the holder of the matching private key can openssl_open it. A successful decrypt() therefore authenticates the sender — there is no separate signature on the callback.
• The bundle cannot verify the amount/order. It proves the message came from Netopia; it does not know what you expected. The consumer must cross‑check IpnResult::$purchaseId against a real, unfulfilled order and confirm IpnResult::$processedAmount before fulfilling. This boundary is documented in src/Resources/doc/index.md.
• Secrets stay out of the compiled container. The extension passes private_key/signature to the configuration object via method calls, not container parameters.
• No card data by default. The hosted‑page flow keeps PAN/CVV off your server; the raw‑card path is documented as PCI SAQ‑D scope.

Project layout

Configuration reference

Defined in config/packages/netopia_mobilpay.yaml (see src/Resources/doc/index.md for full examples):

The application must also define two routes the configuration generates URLs for: netopia_mobilpay_confirm_url (server‑to‑server IPN) and netopia_mobilpay_return_url (browser return).

Inject by interface:

Testing & CI

• PHPUnit 11 (phpunit.xml.dist): bootstraps vendor/autoload.php, runs the tests/ suite, declares src/ as the coverage source, and is strict — failOnWarning="true", failOnRisky="true". Run with vendor/bin/phpunit (or composer test).
• Current suite: 33 tests / 134 assertions, mirroring src/ (config tree, DI wiring, value object, outbound service, IPN enum/DTO/handler). The IPN handler test performs a real openssl_seal → decrypt round‑trip with a generated key pair.
• CI (.github/workflows/ci.yml): on push to main and on pull requests; matrix PHP 8.3 and 8.4 (extensions openssl, mbstring, dom); steps: composer validate --strict, install, vendor/bin/phpunit, and a non‑blocking composer audit.

License

MIT — see LICENSE.md.