Payment Be2Bill Bundle Laravel Package

Getting Started

This bundle is a thin Symfony bridge over rezzza/payment-be2bill (the PHP client for Be2bill's payment gateway). It gives you DI-registered client services and a config tree for your API credentials, plus a redirect flow for Be2bill's hosted checkout page.

Minimal setup:

composer require rezzza/payment-be2bill-bundle

Register in app/AppKernel.php:

new Rezzza\PaymentBe2billBundle\RezzzaPaymentBe2billBundle(),

Configure credentials in config.yml:

rezzza_payment_be2bill:
    identifier: "%be2bill_identifier%"
    password: "%be2bill_password%"
    environment: "sandbox"   # or "production"

Then look first at DependencyInjection/Configuration.php in the source — the alias, environment handling, and service IDs are the thing you need before any code works. The first use case is almost always a redirect (payment page) checkout: you build a payment from an order, redirect the user to Be2bill's URL, and receive a server-to-server notify callback.

$client = $this->get('rezzza.payment_be2bill.client');
$result = $client->request(...); // returns the Be2bill response payload

Version note (2.0.0). A new major release, 2.0.0, is the first since the 2018 1.x line. Release notes point at the changelog diff in PR #34 — read that before you pick your constraint. Install against your Symfony version and confirm the bundle registration, config tree, and client service IDs still match this guide; a major bump is exactly where those can shift. The original 1.x targets Symfony 2/3, so if 2.0.0 does not explicitly support your framework version, verify rather than assume.

Implementation Patterns

Service injection over $this->get(). Inject the client into a payment service and keep controller code thin. Wrap it in your own PaymentGateway interface so you can mock it in tests and swap the bundle out later (see Gotchas).

Redirect checkout flow (the dominant pattern):

1. Create a local Order / Payment entity with a unique IDENTIFIER (order reference) — Be2bill requires it to be unique and stable.
2. Build the parameters array from your order (amount in the smallest unit, currency, CLIENTIDENT, DESCRIPTION, ORDERID).
3. Call the client to get the redirect URL, persist the pending payment state, then redirect() the user.
4. Be2bill redirects back to your RETURN_URL and calls your NOTIFY_URL server-to-server. Trust the notify, not the return redirect.

Notify/callback endpoint. This is where 90% of the real work is. Create a route that:

public function notifyAction(Request $request)
{
    $payload = $request->request->all();          // Be2bill POSTs the params
    if (!$this->gateway->verifySignature($payload)) {
        return new Response('KO', 400);            // must respond with the expected string
    }
    $this->orderManager->markPaid($payload['ORDERID'], $payload['TRANSACTIONID']);
    return new Response('OK');
}

Be2bill expects a specific body (OK/KO) and will retry on failure — make the endpoint idempotent (guard on TRANSACTIONID/ORDERID already processed).

Operation matrix — model each Be2bill operation as a method on your gateway wrapper: charge (pay), authorize (pre-auth), capture (settle), refund, and cancel. Day-to-day flows are usually: authorize → capture, or refund by transaction ID against a prior capture.

Testing pattern. Use the sandbox environment plus Be2bill's test cards to drive the full redirect → notify cycle against a tunneled local URL. Keep a fixture set of valid-signed notify payloads so you can unit-test your callback handler without hitting the gateway.

Integration tip. Decouple "payment initiated" from "payment confirmed" with an event (PaymentInitiatedEvent, PaymentConfirmedEvent) dispatched from the notify handler; downstream order, email, and entitlement logic subscribes to those rather than living in the controller.

Gotchas and Tips

• Maintenance history, not abandonment — verify it. The 1.x line went quiet after Feb 2018, but 2.0.0 has now shipped, so "dead dependency" no longer holds outright. That said, one major release does not prove sustained maintenance: read PR #34, check whether 2.0.0 actually supports your Symfony/PHP versions, and pin a constraint you have tested. Expect the original code to have been built against Symfony 2/3; treat any 2.0.0 compatibility claim as something to confirm in CI.
• Version-specific surface changes. Major bumps are where the config key names, service IDs, and response/DTO shapes move. Re-check Configuration.php and the service definitions in 2.0.0 against whatever examples you copied from 1.x. If service IDs changed, your $this->get('rezzza.payment_be2bill.client') and container wiring need updating.
• Amount units. Be2bill works in the smallest currency unit (cents). Off-by-100 bugs are the most common integration error; centralize the conversion in one place.
• Never trust the return redirect. A user can hit your RETURN_URL without paying. Only the signed NOTIFY_URL callback should flip an order to paid.
• Signature verification is mandatory and depends on your configured password/key. If verification fails in sandbox, log both the raw payload and the computed hash — Be2bill's signing covers a specific ordered subset of params, and any dropped field breaks it. If 2.0.0 reworked the signing/verification code (a likely candidate for a major bump), re-test with captured payloads rather than assuming 1.x behavior.
• Idempotency. Be2bill retries notifies. Deduplicate on TRANSACTIONID and make the handler safe to run twice; also use unique, immutable ORDERIDs so a retried charge can't double-bill.
• Callback reachability. Be2bill calls from its own IPs. Use a fully public HTTPS NOTIFY_URL, not localhost; if you need IP allowlisting, whitelist Be2bill's ranges rather than disabling checks.
• Config secrets. Put identifier/password in parameters or env, never in the committed config. The bundle's config tree predates Symfony's secrets vault.
• Extension points are thin. There's no event dispatcher inside the bundle itself — your own gateway wrapper is the extension point. Wrap the client, define your own DTOs, and don't let Be2bill's raw array payloads leak into domain code.
• Debugging. Enable sandbox and log the full request/response around the client; the underlying library gives sparse exception detail. When something silently fails, the response payload's EXECCODE/MESSAGE fields are the actual error, not the exception message.
• Exit strategy. Keep your PaymentGateway interface narrow so you can swap in the official be2bill/be2bill-php SDK (or the current Dalenys/Ingenico API) without touching business logic. The 2.0.0 release reduces the urgency of a migration but does not remove the value of insulating your domain from gateway-specific array payloads.