Weave Code
Omnipay V3 Bridge Laravel Package
payum/omnipay-v3-bridge
Payum bridge for Omnipay v3 gateways. Use Omnipay’s 25+ payment providers through Payum’s capture/status workflow with built-in return/cancel URL handling, consistent gateway configuration, and Payum-style requests and models.
The bridge for omnipay v3 library
Frequently asked questions about Omnipay V3 Bridge
- How do I install and configure payum/omnipay-v3-bridge in a Laravel project?
- First, install the package via Composer: `composer require payum/omnipay-v3-bridge`. Then, configure Payum to use Omnipay gateways by defining a gateway factory in your Payum builder. For example, to use Stripe, add `->addGateway('stripe', ['factory' => 'omnipay_stripe', 'apiKey' => 'your_key'])` to your Payum configuration. Ensure you also install the specific Omnipay gateway (e.g., `omnipay/stripe`).
- Which Laravel versions and Payum versions does this package support?
- This bridge requires **Payum v1.3+** and is compatible with Laravel projects using PHP 7.4+. It does not directly depend on Laravel but integrates with Payum, which is framework-agnostic. Always check the [Payum documentation](https://github.com/Payum/Payum) for Laravel-specific compatibility notes, as Payum itself may have Laravel-related extensions.
- Can I use this bridge with Omnipay v2 gateways?
- No, this bridge is specifically designed for **Omnipay v3** gateways. Omnipay v2 and v3 have incompatible APIs, so you cannot use v2 gateways with this package. If you’re using Omnipay v2, you’ll need to migrate to v3 or use Payum’s native gateways instead.
- How do I handle payment redirects (e.g., PayPal, Stripe) with this bridge?
- The bridge automatically generates **return and cancel URLs** for Omnipay gateways that require redirects (e.g., PayPal Express). These URLs are unique and managed by Payum’s storage system. After a redirect, Payum will handle the response and update the payment status accordingly. You can access the final status using `GetHumanStatus` to check if the payment was captured or failed.
- What’s the difference between using this bridge vs. Omnipay directly in Laravel?
- This bridge adds Payum’s **state machine, storage models, and workflow orchestration** on top of Omnipay. With Omnipay alone, you’d manually handle redirects, status checks, and payment retries. The bridge simplifies this by integrating Omnipay’s gateways into Payum’s `Capture`, `Authorize`, `Refund`, and `GetHumanStatus` flows, making it easier to manage complex payment scenarios like async captures or retries.
- How do I test payment flows with this bridge in Laravel?
- Use Payum’s built-in testing utilities to simulate payment requests. For example, mock the Omnipay gateway responses in your tests by injecting a custom `GatewayFactory` or using Payum’s `TestGatewayFactory`. Test all critical flows: successful captures, failed authorizations, refunds, and redirects. Ensure your tests cover both happy paths and edge cases like declined payments or gateway timeouts.
- Is this package actively maintained? What if I encounter issues?
- As of 2024, this package has not seen updates since 2022, and there’s no active maintenance. If you encounter issues, check for community forks (e.g., `payum/payum-bundle`) or contribute patches directly. Monitor the [GitHub issues](https://github.com/Payum/OmnipayV3Bridge/issues) for unresolved problems. For critical projects, consider alternatives like Payum’s native gateways or direct Omnipay v3 integration.
- Can I use this bridge with Laravel’s built-in queue system for async payments?
- Yes, you can integrate this bridge with Laravel’s queues to handle async payment processing. Dispatch a job (e.g., `CapturePayment`) that uses Payum’s `Capture` request, then process the result later. Payum’s storage system (e.g., `ArrayObject` or a database-backed storage) will persist the payment state until the job completes. This is useful for high-traffic sites where immediate processing isn’t required.
- How do I handle gateway-specific errors (e.g., Stripe’s card_declined) in the frontend?
- Gateway-specific errors are surfaced in Payum’s `GetHumanStatus` response. After a payment attempt, call `$payum->getGateway()->execute(new GetHumanStatus($payment))` to check the status. The response will include details like `isCaptured()`, `isPending()`, or `getMessage()`. Map these to your frontend error states (e.g., show a declined card message if `getMessage()` contains `card_declined`).
- What are the performance implications of using this bridge vs. Omnipay directly?
- The bridge adds a thin abstraction layer between Payum and Omnipay, which may introduce minimal overhead (e.g., request/response translation). Benchmark your specific use case, but in most scenarios, the difference is negligible. If performance is critical, cache Omnipay gateway instances (e.g., `$gateway = Omnipay::create('stripe')`) and reuse them across requests. For high-volume systems, direct Omnipay usage might be slightly faster, but the trade-off is losing Payum’s workflow benefits.
Weaver
How can I help you explore Laravel packages today?