Download the PHP package digitaltunnel/moyasar without Composer

Moyasar for Laravel

A typed, testable, batteries-included SDK for the Moyasar payment gateway with first-class Laravel integration. Credit cards, Apple Pay, Samsung Pay, STC Pay, tokenization, invoices, and webhooks — all covered out of the box.

Why this package

• 🎯 Typed end to end — readonly DTOs and enums, not loose arrays.
• 🧱 Fluent builders for every payment source and the create-payment / create-invoice requests.
• 🔁 Webhooks that just work — auto-registered route outside the web group (no CSRF dance), signature verification, idempotent de-duplication, optional queued processing.
• 🧾 Invoices API — hosted payment pages / payment links in two lines.
• 🛡️ Secure-by-default checkout — a verifyCallback() helper that re-fetches and validates the payment before you fulfil an order.
• 🧪 Genuinely testable — a MoyasarFake double, plus 160+ tests, PHPStan level 6, and ~100% type coverage in this very package.

Requirements

Installation

Then run the installer — it publishes the config and prints next steps:

Add your keys to .env:

The webhook route registers automatically outside the web middleware group, so CSRF never applies — you don't need to touch VerifyCsrfToken::$except. Confirm it's live:

Configuration

Every option is environment-driven. Defaults shown.

Note All amounts are integers in the smallest currency unit (halalah). 100.00 SAR = 10000. Use ->amountInMajorUnits(100.00) or Amount::toMinorUnits(100.00) to avoid the classic off-by-100 bug.

End-to-end checkout (credit card + 3DS)

The complete, secure flow — create, redirect to 3DS, then verify on return before fulfilling.

Prefer webhooks as your source of truth for fulfilment (see below). verifyCallback() gives the customer an instant, trustworthy result on return; the webhook guarantees you eventually reconcile even if the browser never comes back.

Payment methods

Apple Pay

Samsung Pay

STC Pay (with OTP follow-up)

Tokenization (card-on-file)

Invoices (hosted payment pages)

Lifecycle & reconciliation

Webhooks

Listen for the typed events anywhere you register listeners:

Available events (each carries $payment + $webhook):

PaymentPaid · PaymentFailed · PaymentAuthorized · PaymentCaptured · PaymentRefunded · PaymentVoided · PaymentAbandoned · PaymentVerified · WebhookReceived (catch-all).

Idempotent by design. Moyasar retries non-2xx deliveries up to 6 times. With the moyasar_webhook_events table enabled, each event is stored by id and claimed before dispatch, so a retried (or forged) delivery never re-fires your listeners. Keep listeners idempotent, and for heavy work either queue your listeners (ShouldQueue) or offload the whole pipeline:

Register your webhook

…or from code: Moyasar::webhooks()->create(url: ..., events: [...], sharedSecret: ...).

Custom route

Set MOYASAR_WEBHOOK_ENABLED=false and wire it yourself:

Local persistence (opt-in)

If you published the migrations, three Eloquent models mirror Moyasar state for reporting:

MoyasarToken and MoyasarWebhookEvent work the same way. Rows are written automatically on API calls and inbound webhooks unless you disable the relevant persistence.* flag.

Money helpers

Exception handling

The full hierarchy:

Testing

Use MoyasarFake to stub the API in your own feature tests:

Helpers: fakePaymentCreated(), fakeValidationError(), fakeAuthenticationError(), webhookFixture(), assertCreated(), assertRefunded(), assertSentCount(), assertNothingSent().

Running the package test suite

Contributing

See SECURITY.md.

License

MIT. See LICENSE.