Sdk Bundle Laravel Package

Getting Started

Reality check first: lemonway/sdk-bundle is a Symfony bundle — it registers a Bundle subclass plus a DI Extension/Configuration tree that auto-wires the underlying Lemon Way PHP SDK client into Symfony's container. Laravel has no registerBundles(), no services.yaml, and no config-tree semantics, so you cannot composer require and activate it. There is no first-class Laravel path here.

What you actually do:

1. Read, don't install. Clone the repo (Bitbucket) and open three files, in order:
   • DependencyInjection/Configuration.php — tells you exactly which config keys the SDK client requires (merchant ID / login / password / API key / environment / endpoint base URL).
   • DependencyInjection/*Extension.php and Resources/config/services.xml (or .yaml) — tells you the client's constructor signature and any injected collaborators (HTTP client, serializer, logger).
   • Dependency.php / the bundle class — tells you the Symfony/PHP/Guzzle version constraints the underlying SDK assumes.
2. Pull the underlying SDK on its own (lemonway/php-sdk or whatever the bundle wraps — check its composer.json require block) to confirm whether it targets the legacy XML v1 API or REST v2. That determines your whole design.
3. Write your own ~150-line Laravel integration — a config/lemonway.php, a LemonwayServiceProvider, and a typed client wrapper — instead of inheriting the bundle.

First use case to validate: wallet creation (CreateWallet) + IBAN registration (RegisterIBAN) + a sandbox money-in, against Lemon Way's test environment. If that loop works through your own client, the rest of the API surface is incremental.

// config/lemonway.php
return [
    'env'        => env('LEMONWAY_ENV', 'sandbox'),
    'merchant_id'=> env('LEMONWAY_MERCHANT_ID'),
    'api_key'    => env('LEMONWAY_API_KEY'),
    'password'   => env('LEMONWAY_PASSWORD'),
    'wallet_ip'  => env('LEMONWAY_WALLET_IP'), // required by the API for wallet ops
    'base_url'   => env('LEMONWAY_ENV') === 'production'
        ? 'https://ws.lemonway.fr/mb/{merchant}/dev/api/'
        : 'https://sandbox.lemonway.fr/mb/{merchant}/dev/api/',
];

Implementation Patterns

1. Bind the client as a singleton in your own service provider. The bundle's whole value is a container registration; replicate that.

$this->app->singleton(LemonwayClient::class, function ($app) {
    return new LemonwayClient(
        $app['config']->get('lemonway.merchant_id'),
        $app['config']->get('lemonway.api_key'),
        // ... whatever the extension file told you
    );
});

2. Wrap the SDK behind your own interface, not a facade over theirs. The bundle is unmaintained and zero-adoption; binding your domain to it forecloses swapping to Stripe Connect, Mangopay, or a direct REST client. A PaymentProvider interface with createWallet(), registerIban(), moneyIn(), transfer(), moneyOut() methods costs an hour and buys optionality.

3. Model the Lemon Way object graph explicitly. Accounts vs. wallets, IBAN statuses, KYC states, and money-in/money-out semantics are domain concepts, not DTOs. Store wallet IDs, IBAN IDs, and KYC document IDs alongside your User/Seller models with a dedicated table — you will need to reconcile against them.

4. Route all outbound calls through Laravel's Http client if you write your own REST client (recommended), rather than inheriting the SDK's Guzzle version. You then get retries, timeouts, and logging for free — and you avoid the Guzzle 5/6 vs 7 conflict the aged SDK will bring.

5. Make non-interactive money movements queued jobs. Wallet-to-wallet transfers and payouts should go through a queue with retry/backoff, not the request/response cycle. Keep only the interactive pieces (create wallet, register IBAN) synchronous.

6. Webhook handler before go-live. Implement /webhooks/lemonway with signature/verification where Lemon Way supports it, idempotency keys on your side, and a replay-safe handler. This is where integration failures concentrate.

7. Reconciliation job on a schedule. Pull Lemon Way statements/transaction lists and diff against your local ledger. Do not assume webhooks are complete or ordered.

8. Log with PII redaction. Wallet IDs, IBANs, and KYC document contents are sensitive — the bundle won't do this for you, and neither will the raw SDK.

Gotchas and Tips

• The Symfony config tree is not a Laravel config file. Copy the keys from Configuration.php, not the structure. Laravel's config() and Symfony's Configuration differ in how they coerce types and enforce required nodes; you'll want explicit validation at boot.
• Environment switching is a real hazard. Sandbox keys reaching production (or vice versa) is the highest-severity failure mode in this domain. Use separate LEMONWAY_* envs per environment, assert at app boot, and never derive the endpoint from a string interpolation of an unvalidated config value.
• Version constraints will bite you. Symfony 2.x/3.x-era bundles typically pull Guzzle 5/6 or symfony/* components that clash with a modern Laravel (Guzzle 7, PSR-18). Don't composer require the bundle to "see what happens" — you'll end up with a broken lockfile.
• Provenance matters here. Personal Bitbucket namespace, 0 stars, 0 dependents, no CI, likely no license file, no advisories feed. That's a supply-chain risk in a payment path. If you must install a fork, pin to a commit hash and vendor it.
• Idempotency is on you. The SDK will not deduplicate requests for you; a retried moneyIn after a timeout becomes a duplicate charge. Generate a request ID per logical operation and persist it before the call.
• Partial failures need a reconciliation sweep, not just try/catch. "Wallet created, IBAN registration failed" is a state you have to sweep, not an exception you can unwind. Write compensating logic up front.
• Which API generation? Determine this from the SDK's composer.json/code before writing anything. The legacy XML v1 and REST v2 have different object models; mixing guidance from one into the other is a common time sink.
• KYC document upload is a common blocker. Size/format limits and timeouts will fail onboarding silently. Build a retry path and surface status to whoever owns merchant onboarding.
• Extension points are nil. There's no upstream to merge from. Assume you own every line you depend on, and budget a quarterly review of Lemon Way's API deprecations against whatever SDK version you've pinned.
• Score ≠ adoptability. The opportunity: 6.59 reflects demand for Lemon Way integration in PHP, not quality of this artifact. Use it to scope effort, not to justify installation in a Laravel codebase.