Payum Lock Request Extension Laravel Package

Product Decisions This Supports

• Idempotency / duplicate-charge prevention as a roadmap item. This package addresses a specific failure class: two requests hitting the same Payum payment token at the same time — e.g. a user double-clicking "Pay", a browser retry, or a gateway IPN/webhook arriving while the return-URL redirect is still being processed. Both paths can read the same "pending" state and each attempt a capture. If you have open incidents or support tickets for double charges, duplicate refunds, or "payment succeeded twice" this is a targeted, low-scope fix rather than a payment-layer rewrite.
• Build vs. buy → actually "buy vs. vendor." The package is a thin Payum extension (a lock wrapper around request handling), 1 star, 0 dependents, last release October 2023. It is not a platform dependency; it is a code snippet with a Composer name. The realistic decision is vendor or fork the class into your own app/ namespace rather than adding a barely-maintained transitive dependency to a payment-critical path. Cost to reproduce is hours, not sprints.
• Feature scoping for webhook/notification hardening. If your roadmap includes "make async payment notifications safe" (IPN, Stripe/PayPal webhooks, queue workers with more than one process), this package is a reference implementation of the locking pattern your engineering team should adopt — even if you write it yourself against Laravel's Cache::lock.
• Use cases where it applies: Payum-backed Laravel apps (via payum/laravel), gateways with out-of-band notifications that can race the synchronous capture path, multi-worker queue setups, multi-instance deployments behind a load balancer, and retry-heavy clients (mobile SDKs, flaky networks).
• Use cases where it does not apply: single-process/single-server deployments where a DB transaction or SELECT ... FOR UPDATE already serializes the operation; stacks not using Payum (Laravel Cashier, direct Stripe/PayPal SDKs); or teams already standardizing on Laravel's atomic locks.

When to Consider This Package

Adopt (or, more likely, copy the pattern) when all of the following hold:

• You are on Payum, not a direct gateway SDK — otherwise the extension's hook points do not exist for you.
• You have a concurrent capture risk you can name: async IPN/webhook handlers, queue workers with concurrency > 1, autoscaling app servers, or a client that retries aggressively.
• You have evidence or a credible threat model — reconciliation mismatches, gateway-side duplicate transaction IDs, or a security/QA finding — rather than a hypothetical.
• Your lock backend is decided: which store (Redis, database, filesystem) and what the TTL/failure behaviour is when the lock cannot be acquired. The package supplies the lock semantics, not the operational answer to "what does the customer see when the lock is held?"
• You accept maintenance ownership. At 1 star, 0 dependents, and a 2023 last release, treat it as sample code: pin it, read every line, and plan to fork.

Look elsewhere (or build in-house) when:

• You are not on Payum. Laravel's Cache::lock() / WithoutOverlapping jobs cover the same ground with first-party support.
• You need distributed correctness guarantees beyond a single lock: idempotency keys at the gateway, an outbox/state-machine for payment transitions, and reconciliation jobs matter more than request-level locking.
• Your team has a dependency policy that bars packages with no recent release, no dependents, and a single maintainer — a fair call on a payment path.
• The real problem is state design, not concurrency. If your payment state machine can't tell "captured" from "capturing," locking masks the bug rather than fixing it.
• You need vendor support or SLAs. There are none here.

How to Pitch It (Stakeholders)

To executives (one paragraph): We have a known class of payment bugs where two simultaneous requests can both act on the same payment — most often a customer double-clicking, a browser retry, or a gateway notification arriving while the customer is still on the confirmation page. The visible symptom is a double charge, a double refund, or a support ticket and a chargeback. This package is a small, MIT-licensed fix for exactly that in Payum-based systems. Because it's a tiny, single-maintainer project on a payment-critical path, my recommendation is not to adopt it as a dependency but to lift its locking approach into our own code — a few hours of engineering, no new supply-chain risk, and it closes the race. Decision requested: approve the small hardening task, not a vendor onboarding.

To engineering (summary): webgriffe/payum-lock-request-extension wraps Payum request handling with a lock so concurrent requests against the same payment token serialize instead of racing. It's an extension, so it plugs into Payum's request/action pipeline; we supply the lock storage and TTL. Assess against: (1) our lock backend of choice (Redis vs DB), (2) behaviour when the lock is contended — do we return a "processing, please wait" response or fail closed? (3) interaction with queue workers and webhook retries, (4) whether we need gateway-side idempotency keys in addition. Given the project's maintenance profile (1 star, 0 dependents, last release 2023), vendor the class into our namespace, write a test that fires two simultaneous captures and asserts one gateway call, and own it from there.