Payline Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. Before anything else, confirm you're actually on Symfony (3.x/4.x era) — there is no service provider, no facade, and no config/payline.php here. If you're on Laravel, the bundle is effectively a reference implementation for the Payline PHP SDK, not something you composer require into app/.

Minimal steps on Symfony:

1. composer require lolautruche/payline-bundle and the underlying payline/payline-sdk.
2. Register Lolautruche\PaylineBundle\LolautruchePaylineBundle in app/AppKernel.php (or config/bundles.php on Symfony 4+).
3. Configure credentials under lolautruche_payline:

   lolautruche_payline:
       merchant_id: "%payline_merchant_id%"
       access_key: "%payline_access_key%"
       contract_number: "%payline_contract%"
       environment: homologation   # switch to production when live
   

4. Grab a test merchant account from Payline's homologation portal before writing any code — you can't exercise the flow without it.

Check the PHP constraint first. v3.0.4 exists solely to "update PHP version support," so the practical thing it changes is which PHP versions Composer will accept. Diff the php requirement in composer.json (and the SDK's) against your runtime before wiring anything up — that single line decides whether the bundle installs on your target PHP at all.

Where to look first: the bundle's DependencyInjection/Configuration.php (authoritative list of config keys), Controller/AbstractPaylineController.php (the intended integration surface), and the README's example controller. The public API is small; read those three files before the SDK docs.

First use case: a single "pay for order" flow — create a web payment, redirect the customer to Payline, handle the return URL, and separately handle the notification (IPN) URL.

Implementation Patterns

Extend the abstract controller for the happy path. The bundle's core convenience is AbstractPaylineController, which exposes helpers to create a web payment and to re-query its result by token. A typical controller action builds a payment payload, calls the create helper, and redirects to the returned Payline URL:

$response = $this->doPay([
    'amount'       => $order->getTotalInCents(), // cents, integer
    'currency'     => 978,                       // EUR numeric ISO code
    'orderRef'     => $order->getReference(),
    'returnURL'    => $this->generateUrl('payment_return', [], true),
    'cancelURL'    => $this->generateUrl('payment_cancel', [], true),
    'notificationURL' => $this->generateUrl('payment_notify', [], true),
]);
// persist $response token against the order, then redirect to the Payline URL

Always persist the token and the order reference together. That mapping is the only way to correlate the return and the notification back to an order.

Separate the three endpoints into three responsibilities.

• Create — builds the payload and redirects. Never trusts client-supplied amounts.
• Return — the browser comes back here with a token. Re-query the payment (getWebPayment/handleResponse style call), check the result code, update the order, then render a receipt. This URL is user-visible and skippable.
• Notification — Payline calls this server-to-server. Parse the token, re-query the payment, update state idempotently, and respond with the literal body OK. Anything else and Payline retries.

Wrap the bundle behind your own service. Even on Symfony, put a PaymentGateway interface in your domain and have the bundle-backed implementation map your Order to Payline's array format. The bundle's payloads are arrays with magic string keys; isolating that conversion is the difference between a one-week integration and a one-week-plus-rewrite when you change PSPs.

Treat the notification as the source of truth, the return URL as UX. The reliable pattern is: return URL triggers a re-query and shows a "processing" state; the notification URL drives the actual order state transition (paid/failed). Use a state machine or at minimum a payment_status column plus a payline_token unique index so duplicate notifications are harmless.

Testing. Configure environment: homologation, use Payline's documented test cards, and assert on the numeric result codes rather than the human-readable messages. Write one integration test per outcome (authorized, refused, cancelled, expired) using the notification endpoint. Run at least one job on the exact PHP version you'll deploy — that is now the axis the package actively moves.

Gotchas and Tips

• Framework mismatch is the biggest one. It's Symfony-only; if you're on Laravel you'll be reading this bundle for its structure and copy-pasting the SDK usage. Budget for that translation.
• PHP-version support moved; behaviour did not. v3.0.4 is a compatibility-only bump ("Update PHP version support"). Treat it as a green light to upgrade PHP, not as a feature or fix release — verify the constraint in composer.json actually covers your runtime rather than assuming, and re-run your integration tests after the bump since the code paths themselves are unchanged.
• Maintenance risk (narrowed, not gone). PHP support is now current-ish, but the bundle is still a low-activity, single-maintainer project with no dependents. API drift against Payline and the SDK is still your problem; check that payline/payline-sdk installs cleanly on the newly-supported PHP before committing.
• Amounts are in cents and integers. 19.99 means 1999. Silent rounding bugs here are common and expensive.
• Currency is the numeric ISO code (978 for EUR), not the string "EUR".
• The return URL is not proof of payment. Anyone can hit it. Only trust the result of a server-side re-query, ideally triggered by the notification.
• Notification endpoint must be public and auth-free. No CSRF, no session middleware, no auth guard. Respond exactly OK with a 200; log the raw body before parsing so you can debug retries.
• Idempotency. Payline retries notifications. Use the token as a unique key and make your handler safe to run twice.
• Environment switch is a config value, not a code path — but credentials differ between homologation and production. Keep both in parameters and never let production keys into the dev container.
• Debugging: enable the SDK's debug/trace mode in homologation and log every request/response pair. The bundle's exceptions are thin; the real error is usually in the SDK response's result.code/result.longMessage.
• Extension points: you can override the abstract controller, decorate the gateway service, or drop to the raw SDK for features the bundle doesn't cover (wallet, recurring, refunds). Don't fight the bundle — call the SDK directly for anything beyond a simple web payment.
• Version pin everything. Given the release cadence, stay on the latest patch (^3.0.4) but pin the bundle and SDK together in composer.json, and record the PHP constraint alongside them so a future platform upgrade is a deliberate, tested step.