Download the PHP package fynduck/laravel-maib-ecommerce without Composer

Laravel maib e-Commerce

A Laravel package for the maib (Moldova Agroindbank) e-Commerce payment gateway. It implements the maibmerchants e-Commerce API natively in Laravel — HTTP client, container bindings, a facade, config, events, signature verification and an optional payments table.

Requirements

• PHP 8.2+
• Laravel 10, 11, 12 or 13

Installation

Publish the config:

Add your project credentials (issued in the maibmerchants.md dashboard after activation) to .env:

The access token is generated, cached and refreshed automatically — you never handle tokens.

Usage

All methods are available on the Maib facade and return a PaymentResult object.

Direct payment

Only amount, currency and clientIp are required; everything else is optional. You can pass the Currency and Language enums instead of raw strings to avoid mistyping — the client converts them automatically:

The same optional keys (description, clientName, email, phone, orderId, delivery, items, okUrl, failUrl, callbackUrl) apply to hold(), saveRecurring() and saveOneclick(). For the authoritative, always-current list of every parameter and its constraints, see the maib e-Commerce API docs.

Two-step payment (hold + complete)

Refund

Payment info

Recurring & one-click

Callbacks (webhooks)

maib sends a signed notification to your callbackUrl after each payment. The package registers a route (default POST /maib/callback, named maib.callback) guarded by a signature-verification middleware. Requests with an invalid signature are rejected with a 403 before reaching your application.

On a valid callback the package dispatches:

• Fynduck\MaibEcommerce\Events\PaymentCallbackReceived — every callback
• Fynduck\MaibEcommerce\Events\PaymentSucceeded — when status is OK
• Fynduck\MaibEcommerce\Events\PaymentFailed — when status is FAILED

Each event carries a CallbackResult ($event->callback) with a typed PaymentResult ($event->callback->payment) and the raw verified result array.

Registering listeners

Map a listener to the event in your App\Providers\EventServiceProvider:

On Laravel 11+ the EventServiceProvider is no longer in the default skeleton. You can still create it (and register it in bootstrap/providers.php), or just bind the listener in AppServiceProvider::boot(): Event::listen(PaymentSucceeded::class, MarkOrderAsPaid::class);

Run listeners on the queue (recommended)

The callback request comes from maib and is waiting on your HTTP response — and maib may retry the notification if you are slow or error out. Do not do slow work (DB writes, sending mail, calling other APIs) inline in the listener: that blocks the response and risks duplicate callbacks. Instead make the listener queued by implementing ShouldQueue, so the controller returns 200 immediately and the work runs on a worker:

Make sure a queue worker is running (php artisan queue:work). Because callbacks can be re-delivered, keep listeners idempotent — key off payId so processing the same notification twice is harmless.

Security: the signature is validated using your MAIB_SIGNATURE_KEY with the maib algorithm (recursive key sort → append key → :-join → base64(sha256())) and a timing-safe comparison. Never expose the signature key.

Optional payment persistence

To record every callback in a maib_payments table:

Then set MAIB_STORE_PAYMENTS=true. Incoming callbacks are upserted into the Fynduck\MaibEcommerce\Models\MaibPayment model (keyed by pay_id). The core client works without this table — persistence is entirely opt-in.

Testing

License

MIT