Download the PHP package iabduul7/laravel-moyasar without Composer

Laravel Moyasar

A modern, opinionated Laravel package for the Moyasar payment gateway. Built for Saudi Arabian e-commerce: mada, Visa, Mastercard, Apple Pay, Google Pay, Samsung Pay, and STC Pay.

Status: v0.2.0-dev — Adds Tokens, Payouts, the Money value object, a specialised exception hierarchy, the Sadad source type, and MoyasarTestCards. v0.1.0 covered Payments, Invoices, Webhooks, Events, and an Eloquent trait.

Why this package?

Other Moyasar Laravel packages exist. This one is the only one that:

• Handles webhooks end-to-end. Constant-time secret_token verification, cache-backed replay protection, and a typed Laravel event per Moyasar event type. The other packages leave you to parse the JSON yourself.
• Ships eight typed events (PaymentPaid, PaymentFailed, PaymentAuthorized, PaymentCaptured, PaymentRefunded, PaymentVoided, PaymentAbandoned, PaymentVerified) — not one generic "transaction created" event.
• Has a real Eloquent layer. HasMoyasarPayments trait + polymorphic moyasar_payments table + automatic webhook→DB sync. Attach payments to Order, Subscription, anything.
• Is built for modern Laravel. PHP 8.2+, Laravel 11/12/13, strict types everywhere, readonly DTOs, backed enums. Tested under PHPStan level 8.
• Uses Laravel's own HTTP client. Http::fake() works out of the box for downstream tests. No Guzzle wiring, no Mockery.
• Is idempotency-aware via Moyasar's given_id and retries 5xx automatically (never 4xx).
• Is MIT-licensed. Safe for commercial use, no GPL contamination.

Requirements

• PHP 8.2+ (the test suite itself requires 8.3+ due to Pest 4 — runtime works fine on 8.2)
• Laravel 11.x, 12.x, or 13.x

Installation

Publish the config and migration:

Configuration

Add your keys to .env:

Get test keys from your Moyasar Dashboard → Settings → API keys.

All values, including the webhook route, retry behaviour, logging, and replay-cache TTL, live in config/moyasar.php.

Quick start

Payments

Idempotency

Moyasar supports an idempotency key called given_id on payment creation. Pass a UUID v4 to safely retry the same request:

Errors

All non-2xx responses raise an Iabduul7\Moyasar\Exceptions\ApiException that carries statusCode, type, errors, and the full decoded payload:

5xx responses and connection errors are automatically retried (count + delay are configurable). 4xx responses are never retried.

Typed exception hierarchy

ApiException::fromResponse() returns the most specific subclass available so callers can catch by intent:

Card-level exceptions win over generic status mapping. Each carries sourceMessage and sourceResponseCode as readonly properties for forensic logging.

Money

Use the Money value object to convert between major-unit decimals and Moyasar's smallest-unit integers — the #1 source of integration bugs:

Invoices

Tokens

Server-side tokenisation for trusted-environment flows (admin tools, card-on-file migrations). For browser tokenisation, use Moyasar's JS SDK with your publishable key — the PAN never touches your server that way.

Payouts

Bulk payouts and payout-account endpoints aren't wrapped yet — open an issue if you need them.

Testing helpers

Webhooks

The package registers a POST /moyasar/webhook route automatically (configurable). Add the URL to your Moyasar dashboard with the same secret you set in MOYASAR_WEBHOOK_SECRET. Moyasar embeds that secret as secret_token inside the webhook body — the package verifies it in constant time and rejects any mismatch with a 401.

Replay protection caches each event id for MOYASAR_WEBHOOK_REPLAY_TTL seconds (default 24h). A redelivered event returns 200 but is not dispatched a second time.

Events

Listen for the events you care about:

All eight Moyasar event types are mapped:

Eloquent integration

Add the HasMoyasarPayments trait to any model that needs to track payments:

When webhooks arrive, the package automatically updates any existing moyasar_payments row keyed by moyasar_id — your local copy stays in sync without any wiring. Disable via MOYASAR_WEBHOOK_SYNC_ELOQUENT=false.

MoyasarPaymentCast

Cast a payment-ID column to a live PaymentData DTO (lazy fetch + per-instance cache):

Reading the attribute calls the Moyasar API. Use sparingly to avoid N+1.

Testing your integration

Downstream apps should fake the Moyasar HTTP API the same way the package's own suite does:

For webhook tests, post a JSON body that includes a matching secret_token and assert against the dispatched event with Event::fake([PaymentPaid::class, ...]).

Saudi-specific notes

• Amounts are in halalas. 100 halalas = 1.00 SAR. The DTOs expose both amount (int, halalas) and amount_format (string, e.g. 100.00 SAR).
• mada is the Saudi domestic card scheme. It is selected automatically by Moyasar based on the BIN — clients just send the card number.
• STC Pay uses the stcpay source with a Saudi mobile number (05xxxxxxxx, +9665xxxxxxxx, or 009665xxxxxxxx).
• Apple Pay / Google Pay / Samsung Pay must be tokenised on the client. Pass the encrypted token under source.token (Apple/Samsung Pay) or as a generic token-type source (Google Pay).

Configuration reference

Contributing

Pull requests welcome. Before submitting:

Run the full check locally:

Security

Found a security issue? Email [email protected] rather than opening a public issue.

License

MIT — see LICENSE.