Plorea Laravel Package

Product Decisions This Supports

• Monetization model: software vendor vs. payment facilitator. The package routes every payment to a merchant org number (->merchant(orgNr: ...), always the invoice issuer's, never the platform's). That is a product decision, not a technical one: it means funds and KYC sit with your customers, you stay out of money-transmission territory, and you can sell to gyms/clubs/studios who want their own payouts. If the roadmap instead assumes you collect and split revenue yourself, this package is the wrong primitive.
• Onboarding design. KYC is implicit — the first live payment for a new org number starts it automatically, payouts are held 1–5 business days, and there is no KYC API (the vendor's suggested workaround is a self-addressed payment link). That forces a product answer: do you market "start selling today, payout after approval," or do you build a pre-launch onboarding step and set expectations in the UI?
• Checkout surface roadmap. Three tiers are available: hosted pay page (zero integration), embedded Adyen Drop-in in your own page, and native iOS/Android Drop-in. The skill explicitly recommends the hosted page unless embedded is required. That is a cheap v1 → differentiated v2 path, and it lets you defer CSP, origin whitelisting, universal-link/App Link verification, and Apple Pay domain verification.
• In-app purchase exposure. Apple/Google require IAP for digital goods consumed in-app; real-world services (memberships, classes, invoices) are generally exempt. This determines whether your mobile roadmap carries a 15–30% platform tax and a separate entitlement model, or ships payments untouched.
• Subscription and retention features. Card-on-file setup (RecurringType::Subscription) plus subscriptions()->needingAttention() unlocks recurring membership billing, dunning, card-expiry recovery, and failed-charge win-back — provided you accept that card setup, cancel and reactivate emit no webhook and require a scheduled poller.
• Pay-by-link as the default invoice flow. firstOrCreate() with per-reference locking, suffix chaining, and PaymentAlreadyPaidException supports a "resend invoice / pay now" loop without duplicating charges — useful for collections, reminders, and self-serve renewal.
• Build vs. buy. The alternative is direct Adyen integration plus your own merchant-onboarding, KYC orchestration, and payout routing. This package buys the Laravel-shaped convenience layer over that; it does not buy you SLAs, event durability, or idempotency.

When to Consider This Package

Consider it when most of these hold:

• You are a Laravel/PHP shop billing for real-world services in the Norwegian/Nordic market — memberships, classes, invoices, physical goods — where the payee is your customer, not you.
• Your product needs merchant-specific payouts and per-merchant KYC but you do not want to become a payment institution.
• You want a facade + DTOs + Plorea::fake() so payments are testable in CI and the API key never leaves the server, rather than hand-rolled HTTP against Adyen.
• Hosted payment links are acceptable for v1, with embedded or native checkout as an opt-in later.
• You can absorb the operational work the SDK does not do: idempotent booking on your reference, Cache::lock() around link creation, queued webhook listeners that persist before processing, a polling backstop, and alerts on 4xx/ConnectionException.

Look elsewhere when:

• You need multi-currency, non-NOK billing or markets outside the vendor's/Adyen's footprint — amounts are minor-unit NOK and the surface is Norway-shaped.
• You need capture control (partial captures, manual capture, auth-then-ship). Capture is automatic and there is no capture API; authorised is terminal.
• Event durability is critical. Plorea does not redeliver failed webhooks, and a 500 loses the event permanently. If you cannot guarantee persistence-before-ack plus a poller, this is the wrong rail.
• You need PSP-level idempotency on writes, or you cannot tolerate PLOREA_RETRY_TIMES=0 (retried link creation or charges double-bill).
• You require vendor SLAs, support contracts, or a community. 0 stars, 0 dependents, a single maintainer, and a documented "unverified" list (Android Drop-in on device, native 3DS2, live environment, wallets) mean you are an early adopter, not a customer.
• Wallets are a launch requirement — Apple Pay/Google Pay depend on the provider's Adyen account setup and per-domain Apple verification you cannot control.
• Your scale justifies a direct Adyen relationship with your own merchant account; the abstraction then costs you control rather than saving you work.

How to Pitch It (Stakeholders)

To executives: This is a revenue-enablement dependency, not a feature. It lets us invoice and take card payments for our customers' memberships — including recurring billing — without holding funds, obtaining a money-transmitter license, or owning KYC. Money routes to each customer's own org number; onboarding is triggered by their first payment and pays out 1–5 business days after approval, which we should surface honestly in the sales pitch. Time-to-first-paid-invoice is a config file plus one endpoint, against months for a bespoke integration. The strategic ask is small; the constraint to accept is that we are an early adopter of a thin vendor SDK, so we fund the reliability work (pollers, alerting, idempotent booking) as part of the launch, not after it.

To engineering: Laravel-native facade, typed DTOs, Plorea::fake() for CI, server-side sessions only, toCheckout() serialization so we never leak tenant/shopper/customer ids. Everything painful is on our side and must be scoped: per-reference locks and firstOrCreate() for link creation, idempotent booking (webhook, poll and return page all race), persist-then-process webhook listeners deduplicating on eventId, CSRF exclusion on the webhook path, a scheduled backstop for the events that are never emitted (card setup, cancel, reactivate, lost subscription.charge_failed), refund polling sized in hours, and alerts on 4xx plus stuck links and pending_setup past expiry. Do not expose capture(). Embedded/native checkout adds CSP for Adyen hosts, origin and app-id whitelisting, and a return page that completes redirectResult and strips it via history.replaceState.

To the delivery team / launch gate: Ship hosted links first, prove one low-value live payment per surface with a KYC-approved merchant, verify the webhook is booked exactly once, then run a refund. Add embedded checkout only when a customer-facing conversion problem justifies the whitelisting and CSP work; treat Android, native 3DS2, live environment and wallets as unproven until observed.