Bagisto Clover Laravel Package

Getting Started

ashrafic/bagisto-clover is a Bagisto (Laravel e-commerce) payment-gateway integration for Clover. Treat it as a payment method package, not a general-purpose utility: nearly everything you touch will be a Bagisto payment abstraction, a config key, or a Clover API call.

First steps:

1. composer require ashrafic/bagisto-clover in a Bagisto application (not a bare Laravel app — Bagisto's Webkul\Payment contracts and payment_methods config are hard dependencies).
2. Read composer.json before installing. This is the single most important step for v3.0.0 (see Gotchas). Confirm the bagisto/bagisto / webkul/* constraint range matches your store's version, and confirm the PHP constraint.
3. Publish and inspect the config:

   php artisan vendor:publish --provider="Ashrafic\Clover\CloverServiceProvider" --tag=config
   

   The package's service provider (auto-discovered) is the map of the whole package — check whether it registers a payment method, a route group for webhooks/callbacks, a view namespace for the checkout form, and any migrations.
4. Set credentials in .env: Clover merchant ID plus the API token / OAuth access token for your environment. Keep sandbox and production values in separate env blocks — do not swap them by editing config files.
5. Enable the method in Bagisto's payment configuration (Admin → Settings → Sales → Payment Methods) and give it a title/description and an active flag. Nothing charges until this row exists.
6. First real use case: a customer selects Clover at checkout, is redirected to or embedded in Clover's hosted payment page, and returns to a Bagisto order whose payment status is correct.

If the provider name or tag above doesn't match, run php artisan vendor:publish with no arguments and look for the Clover entry — never guess the tag in a deployment script.

Implementation Patterns

Extend the payment method, don't bypass it. Bagisto resolves payment methods from config into classes implementing its payment contract. Keep any store-specific behaviour (extra logging, order comments, fee surcharges) in a subclass registered via the config key rather than by editing vendor code, so composer update stays safe.

Configuration layering. Keep package defaults in config/clover.php untouched; put per-store overrides in config/services.php or an env-driven block, and remember php artisan config:cache in every deploy. Payment packages are the classic victim of a cached config holding a stale sandbox key.

Server-side charge creation, webhook-confirmed status. The reliable pattern is: Bagisto creates the order in a pending state → you create the Clover charge/session server-side using the order total and a generated idempotency key → the customer pays on Clover → the browser returns to your success route and Clover posts a webhook. Trust the webhook for fulfilment, use the return route only for UX. Make both routes idempotent on the Clover charge/payment ID so a double callback doesn't create a second invoice or duplicate shipment.

Order lifecycle hooks. Bagisto emits events around order placement and invoice creation; hook the invoice-paid path to capture/settle if you're doing auth-then-capture. For refunds, Bagisto's admin refund action is the right seam — map it to the Clover refund endpoint and record the Clover reference on the transaction so support can reconcile.

Testing. Use Http::fake() against the Clover client for unit tests of success, decline, and timeout paths, and assert on order payment state rather than on the outgoing payload where possible. Run one manual sandbox purchase per release — gateway packages rarely have integration coverage that catches API drift.

Multi-store and multi-currency. If the package resolves credentials from a single config key, add a small resolver keyed on store()->id early. Retrofitting multi-store credentials after go-live is painful because orders already reference the old merchant.

Gotchas and Tips

• v3.0.0 ships with no changelog. The release notes are only a v2.0.5...v3.0.0 compare link. A major bump on a payment package means you must read the diff yourself before upgrading. Review at minimum: the service provider, the payment method class, any published config file, and the gateway client's request/response shapes. Assume breaking changes to config keys, class namespaces, and the Clover API version used.
• Upgrade path: upgrade in a branch, re-publish and diff the config (--force overwrites — copy it aside first), clear config and view caches, and run a sandbox transaction before merging. Payment bugs surface at checkout, not in CI.
• Bagisto version coupling. Payment packages pin against internal Webkul classes that move between Bagisto releases. If your Bagisto version is outside the newly declared constraint, composer will silently hold you on v2.x — check composer why-not rather than assuming the upgrade happened.
• Sandbox vs production credentials are not interchangeable. Mistyped environment pairings typically manifest as auth failures at charge time, i.e. in front of a customer. Gate the production key behind an explicit env check and log which environment booted at startup.
• Webhook verification. Confirm the package verifies the Clover signature/secret before acting. If it doesn't, wrap the endpoint with your own middleware — an unauthenticated order-completion route is a free-goods exploit. Also ensure the webhook route is excluded from CSRF and from any auth middleware group.
• Payment status mapping is where most bugs live. Clover's statuses (pending/approved/declined/refunded/voided) do not map 1:1 onto Bagisto's payment states. Write down the intended mapping and test declined, voided-after-auth, partial refund, and duplicate-callback cases explicitly.
• Timeouts and retries. Gateway calls should have a short connect timeout plus a job-level retry with an idempotency key. Without the key, a retry after a network timeout becomes a double charge.
• Logging. Log the Clover request ID / charge ID on every transaction and redact tokens and card data. Support triage without these IDs is guesswork.
• Extension points to look for first: the payment method class (override getRedirectUrl/getPaymentView style hooks), the config file's endpoint base URL (point this at a mock server for local work), and the events the package dispatches, if any. If it dispatches none, add your own via an observer on order payment state so downstream systems (ERP, email) don't depend on the gateway.