Download the PHP package ashrafic/bagisto-clover without Composer

Bagisto Clover

Clover Hosted Checkout payment gateway for Bagisto 2.x.

Customers are redirected to a PCI-compliant, Clover-hosted payment page — no card data ever touches your server (SAQ-A PCI scope). After payment, the order, invoice and order transaction are created automatically, verified through Clover's signed webhook with a redirect fallback so an order is never lost if the webhook is delayed.

How it works

• Whichever arrives first settles the payment. The webhook creates and settles the order idempotently (skipping creation when an order already exists), so a payment is recorded even if the customer's browser never makes it back. The success return reuses the webhook's order — waiting a few seconds for it to appear — or creates the order itself when no webhook arrived.
• Cart clearing is the browser's job, always. On every return the cart is deactivated and the guest session binding cleared in the customer's own request — the only place it can be done — even when the webhook already deactivated the cart in the database.
• The webhook (POST clover/webhook) verifies the Clover-Signature header with HMAC-SHA256 against your signing secret; unsigned or forged requests are rejected with 401.
• A payment whose customer and webhook both never made it back can still be recovered by scheduling php artisan clover:settle-abandoned (e.g. every 15 minutes).
• Every session is tracked in the clover_checkout_sessions table (status, payment id, verification source), giving you a full audit trail per checkout attempt.

Features

• Hosted Checkout redirect flow — no card data on your server
• Signed webhook processing (Clover-Signature HMAC-SHA256) with strict rejection of unauthenticated calls
• Idempotent dual-path order processing — webhook and redirect never double-create an order
• Automatic order creation, status update, invoice and order transaction
• Line items for products, shipping, tax and discounts, converted to the smallest currency unit
• Sandbox and production credentials per channel, with separate test merchant settings
• Optional Hosted Checkout page configuration UUID for merchants with multiple payment pages
• Admin configuration UI translated in 22 locales
• Pest unit and feature tests included

Requirements

You also need a Clover merchant account with Hosted Checkout enabled (Ecommerce section of the Merchant Dashboard) and an HTTPS store URL (required by Clover for redirect URLs and webhooks).

Installation

Register the module in config/concord.php (inside the modules array) — this is the only manual step, and it is required by Bagisto's module system for every package:

Run the migration, publish the checkout logo and refresh:

That's it — no core file edits are needed. The webhook route is CSRF-exempt by design (stateless, throttled), and the migration creates the clover_checkout_sessions table. If your app disables package discovery, register the provider manually in bootstrap/providers.php:

When does Clover appear in the store?

• Admin: the configuration page (Configure → Sales → Payment Methods → Clover) appears automatically after installation.
• Checkout: the payment method only appears when it is actually usable — the admin must set Status to ON and provide valid credentials for the active mode (sandbox or production). A payment method without credentials is hidden on purpose, so customers can never reach a dead-end at redirect.

Clover dashboard setup

1. Log in to the Clover Merchant Dashboard.
2. Go to Settings → View all settings → Ecommerce → Hosted Checkout.
3. Generate an Ecommerce API token for the Hosted Checkout integration type:
   • The private token is your API token (Bearer token)
   • Note your merchant ID (mId)
4. In the Webhook section, enter https://your-store.com/clover/webhook, click Generate and copy the signing secret.
5. Leave the dashboard redirect URLs empty — the package sends per-transaction redirect URLs (/clover/success, /clover/cancel) with the checkout session id embedded, and dashboard values would override them.

Configuration

In the Bagisto admin: Configure → Sales → Payment Methods → Clover.

Testing

Sandbox test transaction

1. Create a free account on the Clover Developer Dashboard — a sandbox test merchant is provisioned automatically.
2. Configure the sandbox credentials in the admin (sandbox enabled) and set APP_URL to an HTTPS URL (use a tunnel such as ngrok for local development).

3. Check out and pay with the test cards (per Clover's test card numbers):

   Scenario	Card number
   Successful payment	4242 4242 4242 4242
   Successful payment (debit)	4000 0566 5566 5556
   Declined payment	4264 2815 1111 7771

   Expiry: any future date · CVV: any 3 digits · ZIP: any 5 digits.

   Note that Clover's sandbox approves transactions below $100.00 and returns an error above it — keep the test cart total under $100.

Test suite

The tests run inside a Bagisto installation. Add the suites to the app's phpunit.xml:

Bind the test case in tests/Pest.php:

The feature suite covers the full payment flow: redirect processing, webhook-first processing, the webhook/redirect race, signature rejection and declined payments — no real Clover account required.

Troubleshooting

Open /{admin-url}/clover/diagnostics in the store (any logged-in admin) — it shows:

• the channel's configuration state (sandbox ON/OFF, token/merchant/webhook-secret set)
• the checkout sessions audit trail (status, payment id, verification source)
• the last 100 Clover entries from the application logs

Notes

• Hosted Checkout charges in the merchant's Clover currency — it must match your store's base currency.
• Discounts are sent as a negative line item; verify with a sandbox transaction if your account applies cart-level discounts.
• Webhook requests are rejected (401) when no signing secret is configured — configure the secret before enabling webhooks.

Contributing

Contributions are welcome. Please make sure the existing code style (Laravel preset, pint.json) and the test suite pass:

License

MIT