Paybox Bundle Laravel Package

Getting Started

1. Install and register the bundle (it predates Symfony Flex, so registration is manual):

   composer require plemi/paybox-bundle
   

   Add it to app/AppKernel.php (Symfony 3) or config/bundles.php (Symfony 4):

   new Plemi\PayboxBundle\PlemiPayboxBundle(),
   

2. Configure your credentials under the plemi_paybox (or vendor-prefixed) key. You need the four values from your Paybox back office: site, rang, identifiant, and the HMAC secret key, plus a toggle for the test/sandbox gateway:

   plemi_paybox:
       site: 1234567
       rank: 1
       identifier: 123456789
       key: "your-hmac-secret"
       sandbox: true
   

3. Look here first when reading the source: the bundle's DependencyInjection/Configuration.php (exact config keys and defaults), its Resources/config/services.yml (public service IDs and constructor args), and the service used to build/verify Paybox payloads. Everything else is a thin wrapper over the Paybox HMAC-SHA1 protocol.

4. First use case — a redirect to the payment page: fetch the bundle's request service from the container, hand it the amount (in cents) and a unique reference, and render the auto-submitting form to the Paybox gateway. From there the user pays and is sent back to your return URL, where you verify the signature before touching your order.

Implementation Patterns

Building a payment request in a controller

$paybox = $this->get('plemi_paybox.request'); // check services.yml for the real ID
$form   = $paybox->prepare([
    'amount'    => 4999,                 // 49,99 EUR in cents
    'reference' => 'ORDER-'.$order->getId(),
    'currency'  => '978',                // EUR ISO 4217 numeric
]);
return $this->render('payment/redirect.html.twig', ['form' => $form]);

Verifying the return / IPN Paybox hits you twice: a browser GET redirect to your return URL and a server-to-server POST to your callback URL. Handle both through a single verification path:

public function callbackAction(Request $request)
{
    $payload = $request->request->all() ?: $request->query->all();

    if (!$this->get('plemi_paybox.response')->isValid($payload)) {
        throw new BadRequestHttpException('Invalid Paybox signature');
    }
    if ($payload['response'] !== '00000') {
        // declined — see the response code reference
        return new Response('KO');
    }
    $order = $this->findOrderByReference($payload['reference']);
    $order->markPaid();
    return new Response('OK');
}

Workflow that scales cleanly

• Create the order locally as pending and store the reference before redirecting.
• Treat the IPN POST as the source of truth — the browser redirect can be faked or aborted.
• Make the callback idempotent: guard markPaid() on current order state so replays don't double-process.
• Return the exact OK string Paybox expects, or it will retry. Log raw payloads for reconciliation.

Integration tips

• Wrap the verification in a domain service rather than the controller, so both your webhook controller and any CLI reconciliation command share one isValid() check.
• Use the sandbox flag to swap gateway URLs; never ship production keys in parameters.yml committed to VCS — move them to env vars (%env(PAYBOX_KEY)%).
• If you need custom field names, the bundle templates are overridable via Resources/PlemiPayboxBundle/views/ — mirror the path under app/Resources (or templates/bundles/ on Symfony 4).

Gotchas and Tips

• Amounts are integers in cents. Passing 49.99 silently produces a wrong charged amount or a rejection. Centralize the € → cents conversion ((int) round($float * 100)).
• Signature mismatches are almost always the key or parameter order. Paybox signs a specific concatenation/URL-encoded string in a fixed field order; a key mismatch, a trailing space, or a stripped zero in amount breaks it. Compare your generated string against a known-good sandbox transaction before blaming the bundle.
• Distinguish success from response code 00000. A valid signature with any other code means the payment was declined/aborted — verify both signature validity and the response code.
• Handle the IPN and the redirect separately. The IPN POST may arrive before, after, or even without the browser redirect. Don't rely on session data being present in the callback.
• Unique reference is mandatory. Reusing a reference makes reconciliation impossible and can be rejected by Paybox.
• Symfony version drift. This bundle is Symfony 3/4-era. On Symfony 5+/6+ you'll need to enable the bundle via Flex, convert get() service lookups to autowiring or a service locator, and possibly patch old container/templating APIs. Budget time for this.
• Low-maintenance risk. With 0 dependents and 12 stars, expect no upstream fixes. Fork it, pin the version in composer.json, and keep your verification logic in your code so a bundle swap is a thin change.
• Debugging tip: log the full outgoing form fields and incoming payloads in dev/test only, then diff against Paybox's documented signing example. That comparison resolves the majority of integration issues instantly.