Laravel Paymongo Laravel Package

Product Decisions This Supports

• Payment feature delivery on PayMongo: The package remains the shortest path to accepting cards, GCash, GrabPay, Maya, and QR Ph in a Laravel product, covering payment intents, sources, refunds, payouts, and webhook handling without hand-rolling HTTP clients, signing verification, or DTOs.
• Webhook onboarding as a launch gate: The headline fix — webhook registration no longer failing with parameter_invalid — directly unblocks the "receive payment status updates" workstream. Any roadmap item dependent on asynchronous payment confirmation (order fulfillment, subscription renewal, refund reconciliation, payout reporting) was previously at risk of shipping with a silently broken registration step. Treat this as the resolution of a known adoption blocker, not a routine patch.
• Build vs buy: Reinforces "buy/adopt" for gateway plumbing. The maintenance surface being actively pruned — removing event types PayMongo never actually emits — is evidence the package tracks the gateway's real contract rather than its documentation. That's the kind of ground truth a team would spend weeks rediscovering.
• Roadmap de-scoping: Nine webhook event types are formally out of scope for PayMongo (payment_intent.succeeded, payment_intent.awaiting_payment_method, subscription.activated, qr.paid, qr.expired, refund.succeeded, dispute.created, dispute.resolved, payout.deposited, payout.returned). Do not plan features that assume these events fire. Notable for roadmap: no refund.succeeded, dispute.*, or payout.* events means refund confirmation, dispute handling, and payout reconciliation must be built on polling the API or manual operations. This is a PayMongo platform constraint surfaced by the package, and it should change how those epics are estimated.
• Versioning hygiene / dependency policy: Removal of public WebhookEventType cases and Luigel\Paymongo\Events classes shipped in a patch version (3.0.1). Even though the runtime blast radius is small (these events never fired, so no listener could have been invoked), this is a semver-breaking change in a patch. Justifies pinning the dependency to an exact or tilde constraint and gating upgrades behind the payment test suite.

When to Consider This Package

Adopt when:

• You are building on Laravel/PHP and PayMongo is your (or a) payment provider — Philippines market, GCash/Maya/QR Ph coverage, or a local entity requirement.
• You need first-class Laravel integration: a service provider, config publishing, facades, and native Events/listeners over a generic HTTP wrapper.
• Your flows are intent-and-webhook driven and you can tolerate PayMongo's actual event set — i.e. you confirm payments via payment.paid-class events and WebhookReceived, not the removed payment_intent.* / refund.* / payout.* events.
• You want webhook signature verification and typed event dispatch without building it yourself.

Look elsewhere or wrap carefully when:

• You are upgrading from a pre-3.x version or from 3.0.0: audit every reference to the removed WebhookEventType cases and Luigel\Paymongo\Events\* classes before bumping. Any use statement, match arm, listener registration, or config array referencing them will now fail — even though no such webhook was ever delivered.
• Your product depends on refund, dispute, or payout webhooks. Those are gone (and per the release notes, were never emitted). You will need scheduled polling of the PayMongo API as an explicit architectural component, plus idempotency and reconciliation logic.
• You need payment providers beyond PayMongo, or a provider-agnostic abstraction. This package is a single-gateway wrapper; adding Stripe/Adyen means a separate integration or an in-house adapter layer.
• You require strict semver guarantees from dependencies, or your release process cannot absorb breaking changes in patch releases. Pin versions and expect to read changelogs.
• You need subscriptions with lifecycle webhooks — subscription.activated is not available; subscription state must be derived from your own records or API polling.

Mitigation note: the fallback is sound. Any unrecognized event name still dispatches WebhookReceived, so an untyped catch-all listener remains a viable safety net for gateway changes that outpace the package.

How to Pitch It (Stakeholders)

For executives: We use a maintained Laravel package to integrate PayMongo as our payment gateway. The latest release fixes a defect that could have blocked webhook registration in production — the mechanism by which we learn a payment succeeded. It also removes nine webhook event types that PayMongo never actually sends, which cleans up the integration but tells us something commercially important: PayMongo does not notify us about refunds, disputes, or payouts. Those need to be handled by scheduled polling or manual process, and any roadmap commitment implying real-time refund or payout confirmation should be re-scoped. Net: the fix reduces launch risk; the removals require a small roadmap correction, not new spend.

For engineering: v3.0.1 is functionally a bug fix with a breaking surface. Webhook registration against PayMongo's API no longer returns parameter_invalid from unsupported event types. The removed WebhookEventType cases and Luigel\Paymongo\Events\* classes must be purged from our codebase — use statements, match expressions, listener registrations, and published config. Runtime risk is low (those events were never delivered, so no listener ever executed), but the code will fatal on load if referenced. Two actions: (1) pin the dependency to an exact or ~3.0.1 constraint — a breaking removal in a patch release is a signal to stop floating the version; (2) add regression coverage for webhook registration and for the WebhookReceived catch-all, which is now our forward-compatibility escape hatch for event names the package doesn't model. Also confirm our refund/dispute/payout handling does not assume webhook delivery — if it does, that's a defect we inherited from PayMongo's documented-but-unshipped event list, and it needs a polling design before those features ship.