Sylius Payzen Bundle Laravel Package

Getting Started

1. Install and register. composer require kiboko/sylius-payzen-bundle (v1.0.3 is current; it adds Symfony 6 support via a getAlias() signature fix, so it's the first release usable on a Symfony 6 / Sylius 1.12+ stack), then add the bundle to config/bundles.php:

   Kiboko\SyliusPayzenBundle\KibokoSyliusPayzenBundle::class => ['all' => true],
   

   Clear cache (bin/console cache:clear) and check for migrations under Migrations/ before running doctrine:migrations:migrate — most Sylius payment plugins store credentials as gateway config JSON and add no schema.

2. Find the moving parts before writing code. The bundle is small and thinly documented; spend ten minutes in these files:

   • DependencyInjection/Configuration.php — the exact config keys the extension accepts (site ID, keys, endpoints, sandbox flag). Also confirm the extension alias here — the v1.0.3 fix touched getAlias(), so this is the file the release directly affects.
   • Form/Type/*GatewayConfigurationType.php — what actually appears in the admin form; this tells you which fields are required vs optional.
   • *GatewayFactory.php — the factory name you must select in the admin.
   • Action/*.php — whether it does capture, authorize-and-capture, or redirects.
   • Any Controller/ or Action/ handling the notify/webhook and return URL.

3. Create the payment method. In the Sylius admin: Configuration → Payment methods → Create. Pick the Payzen factory (the key registered in services.xml, often payzen), populate the config form with sandbox credentials, and restrict it to a channel.

4. First use case: sandbox purchase. Configure a test shop ID / keys, add the payment method to a shipping method, add the gateway to checkout (sylius_shop_checkout payment step), then place a test order with a Payzen test card. Confirm you see the redirect to Payzen, the callback to your notify endpoint, and the payment transition to completed. Do refunds and multi-channel setup after this loop works.

Implementation Patterns

• One payment method per channel, one config per method. Sylius stores gateway config per payment method, so multi-store setups mean duplicating credentials per method or injecting a custom config provider. Keep credentials in env vars (e.g. %env(PAYZEN_SITE_ID)%) and use separate payment methods for test and prod rather than flipping a flag.

• Trust the webhook, not the return URL. The plugin typically ships a notify controller (IPN) and a return controller. Mark payments paid only from the notify/IPN path after verifying the kr-hash/HMAC signature; use the return URL purely to redirect the customer to the order summary with a "pending" message. Orders will frequently return before the IPN lands.

• Wrap the HTTP client, don't fork it. Locate the service that talks to Payzen and either decorate it or add a Monolog channel around the request/response. Log the raw kr-answer payload — reconciliation with the Payzen back office is the number one support task.

• Idempotency in the notify handler. Payzen retries notifications. Before transitioning a payment, check current state and the gateway transaction reference so duplicate IPNs are no-ops. Rely on Sylius' payment state machine transitions rather than setting state directly.

• Refunds. If the plugin doesn't ship a refund action, implement one against the Payzen REST API and attach it to the payment method via a RefundPaymentRequest/action. Test the "partial refund" path explicitly — Sylius' refund state machine is easy to desync from the gateway.

• Testing pattern. Unit-test the hash verification and amount conversion with sample payloads. For integration, put the notify URL behind a test you can hit with curl and a recorded kr-answer. Behat scenarios are worth it for the checkout redirect round trip. Run the suite on both Symfony 5.4 and 6.x if you support both — v1.0.3 is the release that makes the 6.x leg possible, and the getAlias() change is the kind of thing that only breaks at container compile time, not at request time.

• Extending safely. Add Sylius event subscribers on sylius.payment.pre_create / payzen.notification.received rather than editing vendor code. Prefer decorating the factory or notify controller if the bundled behavior needs tweaking — the package is small enough that upstream changes can be breaking.

Gotchas and Tips

• The README is probably incomplete. With ~3 stars and no dependents, the source is the documentation. Confirm the gateway factory key, config field names, and endpoint defaults from Configuration.php and the form type before you build admin fixtures or config YAML.

• Factory name mismatch. If Payzen doesn't appear in the admin gateway dropdown, the bundle isn't registered, cache is stale, or the factory lacks its sylius.payment_gateway_factory tag. bin/console debug:container --tag=sylius.payment_gateway_factory will show it.

• Silent webhook failures. A wrong public key or hash algorithm usually yields a 200 with an unpaid/refused status and no Sylius error — only a log line. Verify the hash against the Payzen docs, confirm test vs live keys, and add explicit logging in the notify action.

• Webhook routing and CSRF. The notify endpoint must be publicly reachable and excluded from CSRF, and the firewall access_control must allow it. If IPNs are 302-ing to login, payments will sit in processing forever. Check security.yaml and route requirements.

• Minor units. Payzen sends amounts in cents with a numeric currency code (EUR = 978). Conversion bugs here are common — assert round-trip conversion in a unit test before going live, especially if your catalog currency isn't EUR or you allow zero-decimal currencies.

• Sandbox vs production endpoints. The plugin may default to a regional/test URL. Confirm both the API endpoint and the hosted-payment URL are switched together; a mixed config produces confusing half-working payments.

• Debugging loop. bin/console debug:container payzen (adjust to the real prefix) to find service IDs, tail var/log/dev.log while replaying a captured notify payload with curl -X POST, and check the Payzen back office for the transaction's actual status before assuming Sylius is at fault.

• Compatibility and licensing. v1.0.3's only change is a Symfony 6 container fix (getAlias() return-type signature on the DI extension), which means 1.0.2 and earlier are effectively Symfony 5-only — if you're on Symfony 6, pin ^1.0.3, not ^1.0. The release note is a single line with no migration guide, so still verify the full matrix (Sylius version vs Symfony 5.4/6.x vs PHP) with composer why-not kiboko/sylius-payzen-bundle. Patch releases here are narrow, one-file changes — read the diff on the extension class when bumping, since a signature fix today could become a behavior change tomorrow. Also inspect the LICENSE file — the metadata reports NOASSERTION, so confirm the terms before shipping it in a commercial shop. Given the low adoption, budget for a local fork or patch rather than expecting upstream fixes.