Mangopay Bundle Laravel Package

Getting Started

• Install with Composer: composer require troopers/mangopay-bundle. Note this is a Symfony bundle, not a Laravel package — in Symfony 3/4 you register it in app/AppKernel.php (or config/bundles.php on 4.x); on Laravel you would instead pull the underlying mangopay/php-sdk-v2 and duplicate the config by hand.
• Configure credentials under the troopers_mangopay key (typically in config.yml / config/packages/troopers_mangopay.yaml):

  troopers_mangopay:
      client_id: "%mangopay_client_id%"
      api_key: "%mangopay_api_key%"
      sandbox: true
  

• Look first at DependencyInjection/Configuration.php for the exact config keys, and Resources/config/services.xml for the service IDs the bundle registers (the MangoPay\MangoPayApi client and the helper service are the two you will interact with daily).
• First use case: inject the client (troopers.mangopay.client / the autowired MangoPay\MangoPayApi), create a MangoPay User, then a Wallet, then a PayIn. Almost every MangoPay flow is that three-step chain, so proving it end-to-end in sandbox is the right smoke test.
• Keep a set of sandbox credentials separate from production; the bundle’s sandbox: true flag only points the SDK at the sandbox host — the credentials themselves are still distinct.

Implementation Patterns

• Inject the SDK, don’t wrap it. The bundle’s main value is putting a configured MangoPayApi instance in the container. Use $this->api->Users->Create($user), $this->api->Wallets->Create($wallet), $this->api->PayIns->Create($payIn) directly. The bundle does not abstract away the resource objects, so plan to read the MangoPay PHP SDK docs alongside the bundle code.
• Use the helper service for repeated flows. The bundle ships a helper (troopers.mangopay.helper) that wraps common operations (create user/wallet, etc.) and, importantly, dispatches events. Use it when you want the event hooks; use the raw client when you need an operation the helper does not cover.
• Hook into the event system. The bundle emits events around user/wallet creation (event classes live under the bundle’s Events namespace and the dispatcher constants are on the bundle’s event class). Subscribe to these to attach your domain logic (e.g. persist the returned MangoPay user ID on your own User entity) rather than sprinkling that logic across controllers.
• Store MangoPay IDs, not objects. Persist the returned Id (a numeric string) on your local entities: mangopay_user_id, mangopay_wallet_id, mangopay_card_id. This is the seam between MangoPay and your database, and every subsequent call needs it.
• Webhook controller pattern. Add a controller that accepts MangoPay’s application/json callback, validates the payload (the SDK / bundle helpers give you the signature fields), looks up the related local record by ResourceId, and then dispatches your own domain event. Do not trust the callback body for amounts — re-fetch the resource via the API before mutating state.
• Per-environment config. Drive client_id/api_key/sandbox from parameters that differ by dev/prod, and point your webhook URL config at the matching host. A common bug is a production API key talking to the sandbox host (or vice versa) because the sandbox flag was forgotten.

Gotchas and Tips

• It is Symfony-only and aging (last release 2019). For a Laravel codebase, budget for extracting the SDK wiring into a small service provider yourself; you will not get the bundle’s DI/event plumbing, and you should not try to shoehorn a Symfony bundle into Laravel.
• Money is integers, in minor units, with a currency code. DebitedFunds/CreditedFunds are { Amount: 1234, Currency: "EUR" } — never floats. A very common bug is sending 12.34 and getting a validation error or a silently wrong charge.
• IDs are strings. MangoPay Id values are large numeric strings; casting them to int on 32-bit or JS-front-end round-tripping will corrupt them (big-int precision). Keep them as string end to end.
• Service autowiring is not guaranteed. Older bundles register services with explicit IDs and no aliases. If injection fails, either reference the service ID directly or add an alias in your services.yaml:

  MangoPay\MangoPayApi:
      alias: troopers.mangopay.client
      public: true
  

• Catch the SDK’s exceptions. Wrap calls in try/catch for MangoPay\Libraries\ResponseException (API returned a business error, has GetErrorCode()/GetErrorMessage()) and MangoPay\Libraries\ApiException (transport/auth). Log the error code — MangoPay error codes are the fastest route to the cause (e.g. insufficient funds, invalid card, KYC required).
• Idempotency. For PayIns/Transfers/Payouts, pass an Idempotency-Key header via the SDK’s request options so a retry after a timeout does not double-charge. The bundle does not add this for you.
• Sandbox behaviour differs subtly. Card registration flows, 3DS challenges, and KYC document validation behave differently in sandbox; test with MangoPay’s documented sandbox test cards and expect some flows to succeed immediately where production requires asynchronous validation.
• Debugging HTTP traffic. The SDK can be told to log requests; enable that in dev only, and scrub Authorization headers and card data before it reaches your logs. If calls hang, check outbound network/proxy rules — MangoPay calls are HTTPS to api.mangopay.com/api.sandbox.mangopay.com.
• Extension points are limited. There is no rich plugin surface; your escape hatches are (a) decorator services that wrap MangoPayApi, (b) event subscribers on the bundle’s events, and (c) bypassing the helper and calling the client directly. Prefer wrapping in a thin domain service so an SDK upgrade or bundle replacement touches one class, not every controller.