Mango Pay Bundle Laravel Package

Getting Started

The single most important thing to know before touching this package: it is a Symfony bundle, not a Laravel package. It was archived in 2019, has zero dependents, and exists solely to wire the mangopay/php-sdk (MangoPayApi) into a Symfony 2.7+ service container. In a Laravel app you will almost never composer require it directly, because pulling it in drags Symfony DI and FrameworkBundle constraints into your lockfile for no runtime benefit.

The practical onboarding path is:

1. Read the bundle, don't install it. Clone the repo and look at these three files first, in this order:

   • Resources/config/services.yml — shows exactly which services are registered and how the MangoPay SDK client is constructed.
   • DependencyInjection/Configuration.php — the config tree (client id, API key, base URL / sandbox flag, logging).
   • DependencyInjection/TeknooMangoPayExtension.php — how those config values get injected into the SDK client. You are essentially copying ~40 lines of service definitions into a Laravel service provider.

2. Install the underlying SDK, not the bundle. composer require mangopay/php-sdk-v2 (or whatever pinned version the bundle references). That library is where every useful method lives — the bundle adds nothing on top except DI wiring.

3. Create a Laravel service provider (e.g. MangoPayServiceProvider) that binds a singleton MangoPayApi instance:

   $this->app->singleton(\MangoPay\MangoPayApi::class, function ($app) {
       $api = new \MangoPay\MangoPayApi();
       $api->Config->ClientId  = config('services.mangopay.client_id');
       $api->Config->ClientPassword = config('services.mangopay.api_key');
       $api->Config->BaseUrl   = config('services.mangopay.sandbox')
           ? 'https://api.sandbox.mangopay.com'
           : 'https://api.mangopay.com';
       return $api;
   });
   

4. First real use case: create a natural user (Users->Create) in sandbox, then a wallet (Wallets->Create), then read it back. This validates credentials, base URL, and JSON round-tripping end to end before you build anything else.

The "package" you are actually leveraging is the MangoPay SDK; the bundle is just documentation-by-example for how to configure it.

Implementation Patterns

Because the bundle is a no-op inside Laravel, the patterns below are what your own adapter layer should look like once you've extracted the DI knowledge.

Singleton client + facade. Bind MangoPayApi as a singleton (the SDK holds no per-request state, but recreating it per call means fresh auth negotiation each time). Expose it via a MangoPay facade or a thin MangoPayService with explicit methods (createUser, createWallet, createPayIn, …) so controllers and jobs depend on your service, not raw SDK object paths.

Config-driven environment switching. Put credentials in config/services.php under a mangopay key and back it with env vars. Mirror the bundle's config tree: client_id, api_key, base_url (or a sandbox boolean), and log level. Never hardcode the sandbox base URL in application code — MangoPay sandbox and production are fully separate identity spaces, and mixing them causes "resource not found" errors that look like auth bugs.

Repository-style resource wrappers. A common workflow is: create user → create wallet for that user (scoped to a currency) → register card → initiate pay-in → handle webhook → release funds / refund. Wrap each step in a small class (MangoPayUserRepository, MangoPayWalletRepository) that takes the singleton client. This makes the eventual migration to a newer SDK (or to Stripe/Adyen) a matter of rewriting one class per resource.

Webhook ingestion as a queue job. MangoPay POSTs events with retries and no signature header in older API versions, so validate by re-fetching the resource by its ID rather than trusting the payload. Dispatch a job from the controller, return 200 immediately, and do the heavy lifting asynchronously — the SDK is synchronous and a slow response causes MangoPay to retry.

Idempotency keys on every write. Pass an IdempotencyKey (the SDK supports it via the request options / idempotencyKey argument on Create calls) generated from an application-level unique value (your order UUID). This is the single most important operational pattern — without it, retries after timeouts double-charge or double-create.

Test doubles via container swap. In your MangoPayServiceProvider, allow an override in tests: $this->app->instance(MangoPayApi::class, $fakeApi). Because everything depends on the resolved singleton, you can stub the whole SDK surface instead of mocking HTTP.

Gotchas and Tips

This package is archived and will never receive security patches. Its dependencies (Symfony 2.7/3.x components, old Guzzle, PHP-SDK v2) are years past end-of-life. Do not put it in require of a production Laravel app — you inherit CVEs in transitive Symfony and Guzzle packages. Copy the config and service definitions, leave the bundle out.

Composer conflicts will bite you immediately. A bundle targeting Symfony 2.7+ will try to lock symfony/http-kernel, symfony/dependency-injection and symfony/config at versions incompatible with modern Laravel (which may incidentally use symfony/* for its own internals). You will end up in dependency-resolution hell. Again: read, don't install.

Auto-discovery does not exist. Laravel never loads Symfony bundles. There is no extra.laravel.providers entry. Every service the bundle would have registered, you must register yourself.

API version drift. The bundled SDK targets a MangoPay REST API version from circa 2018–2019. MangoPay's API has changed since: SCA/3DS fields, pay-in method names, and some response shapes differ. When you hit a ValidationError on a field that "used to work" in tutorials, check the SDK version against MangoPay's current API docs, not the bundle's README.

Base URL vs. sandbox flag. The bundle config exposes a base URL; some tutorials show a Sandbox boolean from other wrappers. Use the URL form and read it from config so you can flip environments without a redeploy. Sandbox credentials silently fail against the production URL with a 401 — treat any 401 in a fresh environment as a URL mismatch first, credentials second.

Debugging is underdocumented; enable logging on the SDK directly. The bundle's logging configuration ultimately toggles the SDK's internal logger. In your own integration, set $api->Config->DebugMode = true (or attach a PSR-3 logger if the SDK version supports it) and log request/response bodies during development. The SDK throws typed exceptions (MangoPay_ApiError, MangoPay_ResponseException) — catch MangoPay_ApiError first, inspect getErrorCode() / getMessage(), and map known codes (001999 generic, 001001 insufficient funds) to domain errors.

Extension point is the SDK, not the bundle. The bundle's only real seam was the service container binding. In Laravel, that seam becomes a container binding — so wrap MangoPayApi behind your own interface from day one. That interface is your ticket out when you upgrade to the current SDK or replace the gateway entirely.

Watch the object graph. MangoPayApi exposes resources as properties ($api->Users, $api->Wallets, $api->PayIns, …), each holding a reference back to the client. Serialising these objects (e.g. into a cache or queue payload) will blow up or leak the API key on serialisation. Store IDs, never SDK objects.

Long-term recommendation: treat this bundle as a 2019 tutorial. Budget a short spike to wire the current MangoPay SDK directly into a Laravel service provider and skip the bundle entirely — it is roughly a day's work and saves you from inheriting an unmaintained, unpatched Symfony dependency.