Download the PHP package ahmed-abd0/laravel-paymob without Composer

Laravel Paymob

A community-built, Cashier-inspired Paymob package for Laravel 11, 12, and 13. It wraps the current Paymob Intention, saved-card, subscription, refund/void/capture, transaction inquiry, and Quick Link APIs while keeping a reliable local billing state.

This package is not an official Paymob package. Replace the Composer vendor name before publishing under your own organization.

Why this design

The package has two layers:

1. Raw API resources for direct access to every endpoint.
2. Billing models and workflows for subscriptions, idempotent callbacks, local access checks, trials, grace periods, payment methods, and synchronization.

Redirect responses are never treated as proof of payment. Signed backend callbacks and Paymob inquiry APIs are the source of truth.

Installation

Add Paymob\Laravel\Concerns\Billable to the model that owns subscriptions:

Configure .env:

Supported regions: egypt, ksa, uae, and oman.

Create a Paymob subscription plan

Plans are stored locally in paymob_plans and keep the full remote response for diagnostics.

Start a subscription checkout

For a trial:

When Paymob provides a dedicated 3DS verification integration, pass it explicitly for verification-only enrollment:

The local subscription starts as incomplete. It becomes active only after a verified successful callback.

Subscription checks

valid() returns true while active, on trial, or in a cancellation/suspension grace period.

Manage a subscription

Paymob cancellation is permanent. Creating a fresh subscription is required after cancellation.

Manage cards

To add a secondary card, create an intention with subscriptionv2_id:

Card tokens are encrypted using Laravel's application key. Webhook payloads are also encrypted at rest.

One-off intentions

Saved cards

Customer-initiated payment:

Merchant-initiated payment:

Never expose saved tokens to frontend code.

Refund, void, and capture

Transaction inquiry

Quick Links

Webhooks

The package registers:

Transaction and token callbacks use HMAC-SHA512 validation. Subscription callbacks use a secret embedded in the registered callback URL because the supplied subscription collection does not define a subscription-specific HMAC calculation.

Processing is:

• HMAC/secret verified before state changes.
• Payload hash deduplicated.
• Webhook row locked before processing.
• Transactions and card tokens upserted.
• Subscription state changed atomically.
• Events dispatched after commit.
• Failed callbacks return an error so Paymob can retry.

Available events:

If the callbacks use Laravel's web middleware, exclude these paths from CSRF validation. The default package routes use the api middleware group.

Synchronization and cleanup

Schedule synchronization as a reconciliation fallback:

Raw endpoint coverage

Important production rules

• Use integers in minor currency units (10000 means 100.00).
• Ensure the intention amount equals the sum of items[].amount.
• Test keys only work with test integration IDs; live keys only work with live integration IDs.
• A recurring plan requires a MOTO integration; enrollment normally requires an online 3DS integration.
• Treat callbacks and inquiry responses as authoritative, not browser redirects.
• Keep APP_KEY, Paymob keys, HMAC secret, and tokenized cards outside source control.
• Use HTTPS for every callback and redirect URL.
• Only GET requests are retried automatically; non-idempotent payment operations are not replayed by default.
• Add your own authorization around customer billing-management endpoints.

Custom models

Override model classes in config/paymob.php. Custom models should extend the package model so the relationships, casts, and lifecycle methods remain available.

Testing