Payment Stripe Bundle Laravel Package

Getting Started

The bundle is a Symfony bundle, not a Laravel package — if you're working in a Laravel app, you'll be pulling in the underlying Stripe SDK and wiring it yourself, using this repo mainly as a reference for how Quartet structures payment flows. In a Symfony app, the setup is:

1. composer require quartet/payment-stripe-bundle
2. Register the bundle in config/bundles.php (Quartet\Bundle\PaymentStripeBundle\QuartetPaymentStripeBundle::class => ['all' => true]).
3. Configure your Stripe keys via environment variables (STRIPE_PUBLIC_KEY, STRIPE_SECRET_KEY) — the bundle typically expects these under quartet_payment_stripe in config/packages/.
4. Inject the Stripe client / payment gateway service into a controller or service.

The first use case to validate is a one-off PaymentIntent: create a charge for a fixed amount, confirm it, and inspect the returned status. This exercises the client wiring, config loading, and error handling in one pass before you touch anything more complex.

Look first at the bundle's DependencyInjection/ folder to understand what services and parameters it registers — that's the source of truth for what you can autowire. Then check the EventSubscriber/ or webhook handlers, which is where most of the real logic lives.

Implementation Patterns

Gateway service injection. Rather than calling the Stripe SDK directly, resolve the bundle's payment service from the container. This keeps your controllers testable and lets you swap gateways if you later add PayPal or similar via Quartet's payment abstraction. Type-hint the service interface, not a concrete Stripe class.

PaymentIntent + client-side confirmation. Create the intent server-side, return the client_secret to the frontend, and confirm via Stripe.js. This is the standard pattern the bundle is designed around and keeps you out of PCI scope. Store the intent ID on your order model immediately so you can reconcile later.

Webhooks as the source of truth. Never trust the browser redirect for order fulfillment. Register a webhook endpoint, verify the signature with the bundle's webhook handler, and update order state in the payment_intent.succeeded, payment_intent.payment_failed, and charge.refunded handlers. Idempotency is essential — Stripe retries aggressively, so guard every handler against duplicate events (store the event ID).

Subscription flows. If you're doing recurring billing, prefer Stripe Checkout Sessions or the Billing Portal over building your own — the bundle exposes the underlying client so you can call these directly. Store stripe_customer_id and stripe_subscription_id against your user model and listen to customer.subscription.updated / .deleted for state sync.

Testing. Use Stripe's test-mode keys with the standard magic card numbers (4242… for success, 4000 0025 0000 3155 for 3DS). For webhook tests, use the Stripe CLI (stripe listen --forward-to) locally and assert against your handler subscribers.

Gotchas and Tips

• Symfony-only. There is no Laravel service provider, facade, or config file. In Laravel you'll wrap the Stripe\Client yourself; the bundle is only useful as architectural inspiration.
• Zero dependents, zero stars. Do a fresh composer why-not quartet/payment-stripe-bundle before adopting — it may be pinned to an old Symfony LTS or PHP version you've already moved past. Treat it as unmaintained until proven otherwise.
• Stripe API version drift. The bundle's pinned Stripe SDK may lag the current API version. Set api_version explicitly in your config and test against that version rather than letting Stripe default it.
• Webhook signature verification requires the raw request body. In Symfony, Request::getContent() returns it, but be careful if middleware reads the body first — the signature check will fail with a confusing error. Exclude the webhook route from any body-parsing middleware.
• Amounts are in minor units. 1000 means $10.00. Currency must be a lowercase ISO code. This trips people up in every Stripe integration and this bundle doesn't abstract it away.
• Config quirks. The bundle likely reads parameters like %stripe_secret_key% — check Configuration.php in DependencyInjection/ for the exact tree name. If autowiring a gateway service fails, the bundle may use a factory that requires a manually named alias.
• Idempotency keys. For any create-payment call that could be retried (network errors, queue workers), pass an idempotency key derived from your order ID. The SDK supports it; the bundle won't do it for you.
• Extension point. If you need custom behavior (receipts, metadata, split charges), the cleanest seam is usually a Symfony event subscriber listening on the bundle's dispatch events — check for quartet_payment_stripe.* events rather than forking.
• Debugging failures. Set the SDK logger (Stripe\Stripe::setLogger()) to your Monolog channel; the default is silent. Also enable setAppInfo() so failures are traceable in the Stripe dashboard.