Stripe Laravel Package

Getting Started

1. Install prerequisites. This package is a driver, not a standalone bundle — you need a working lunarphp/lunar install (matching major version) and a Stripe account with API keys already in hand. Add it with composer require lunarphp/stripe.
2. Configure credentials. Publish the Stripe config and set STRIPE_KEY, STRIPE_SECRET, and STRIPE_WEBHOOK_SECRET in .env. Mirror the key pair (publishable/secret, test/live) so your local and staging environments never share live credentials.
3. Register the driver in Lunar's payment configuration (typically config/lunar/payments.php) so your checkout flow resolves the stripe driver. If you only have one payment type, this is a one-line change; otherwise wire it per payment type.
4. Where to look first. Read the payment driver class under src/ end-to-end before touching the config — it's the contract Lunar expects (intent creation, confirmation, refund entry points). Then read the webhook route/controller, because almost every non-trivial Stripe bug you'll hit is a webhook-ordering or signature issue.
5. First use case. Take a card payment end-to-end: create a Payment Intent for a Lunar cart's total, confirm it on the client with Stripe.js/Elements, and let the webhook flip the order to paid. Get this green in test mode before layering on refunds, manual capture, or multi-currency.

Implementation Patterns

• Let Lunar own the payment lifecycle; let Stripe own the money movement. Drive everything through Lunar's Payment model and payment driver interface. Resist the urge to call Stripe's SDK directly from controllers — you'll bypass status transitions and end up with orders that disagree with Stripe.
• Always handle asynchronous outcomes via webhooks. Card payments can succeed, require action (3DS), or fail after redirect. Treat client-side confirmation as "provisional" and only mark an order paid on the payment_intent.succeeded webhook (or the driver's equivalent). Idempotently update Lunar's payment state from the webhook handler.
• Use manual capture for auth-then-ship flows. If you only capture at fulfillment, create the intent with capture_method set to manual and call the driver's capture path at ship time. Make sure your webhook handler distinguishes requires_capture from succeeded.
• Refunds through Lunar, not Stripe dashboard. Use Lunar's refund API so partial refunds, reason codes, and totals stay consistent. The driver maps these onto Stripe refunds; doing it manually in the dashboard desynchronizes totals.
• Test with the Stripe CLI. Forward events (stripe listen --forward-to .../webhooks/stripe) during development so you never wait on production webhooks to see state transitions. Use Stripe's standard test cards (4242…, 4000 0025… for 3DS, 4000 0000 0000 9995 for declines) to exercise each branch.
• Multi-currency and multi-store. If Lunar is configured for multiple currencies, confirm the driver creates intents in the storefront currency and that you aren't relying on Stripe's automatic conversion. Check minor-unit handling (JPY, KRW, etc.) in your own tests — Stripe's smallest-unit rules and Lunar's price storage must align.
• Integration tip: surface intent state on your Payment resource. Persist the Stripe Payment Intent ID (and any client secret you need) on the Lunar payment so support can reconcile an order to a Stripe object in seconds.

Gotchas and Tips

• Read-only subtree split. This repo is a mirror; issues and PRs belong in lunarphp/lunar. Don't fork it expecting merges — patch Lunar upstream or subclass the driver locally.
• Version lockstep. Keep lunarphp/stripe on the same major as lunarphp/lunar. A minor-version skew can change driver method signatures and break checkout silently at the intent-creation step.
• Webhook signature verification fails loudly but late. If STRIPE_WEBHOOK_SECRET is missing or stale (e.g., after recreating a CLI endpoint), verification throws inside the controller and Stripe retries — which looks like duplicate events rather than a config error. Log the raw payload and signature before verifying while debugging.
• Event ordering and duplicates. Stripe guarantees at-least-once delivery, not order. Guard every handler with idempotency (record processed event IDs, or check current Lunar payment status before transitioning). Treat "already paid" as a no-op, not an error.
• Local dev networking. Stripe can't reach localhost directly; use the CLI forwarder, and make sure the forwarded path matches the route this package registers. If you've customized the webhook route, update both the CLI command and the dashboard endpoint.
• Idempotency keys on outbound calls. When retrying intent creation (network blips, queue retries), pass an idempotency key derived from the Lunar payment ID so you don't create duplicate intents and double-charge.
• Error surface. Stripe errors arrive as typed exceptions with codes (card_declined, authentication_required). Catch and translate these into Lunar payment failure states with a human-readable message — don't dump the raw exception into a customer-facing checkout page.
• Extension points. The driver resolves through Lunar's payment manager, so the clean way to customize behavior (custom metadata, statement descriptors, capture timing) is a subclass registered in the payment config, not editing vendor files. Metadata is your best hook — attach the Lunar order/cart ID to every intent so webhooks can resolve the target without extra DB lookups.
• Test mode hygiene. A single stray STRIPE_SECRET pointing at live keys during a test run is the classic way to move real money in dev. Gate test-mode assertions on the key prefix (sk_test_) and fail fast at boot if it doesn't match the environment.