MA Lara Payment

A unified Laravel payment package for integrating multiple payment gateways through a consistent API.

Documentation   •   Testing   •   Contributing   •   License

Documentation

ma-lara/payments provides a unified API for integrating multiple payment gateways into Laravel applications.

The package exposes common operations such as:

• pay()
• verify()
• retryPayment()
• refund()
• Transaction queries

Each gateway implements the package's gateway contract while keeping provider-specific API calls, authentication, response mapping, and webhook handling isolated inside the gateway implementation.

Supported Gateways

Important

The package backend is frontend-agnostic.

The package includes an optional Stripe Blade card component, but you can integrate the backend with:

• Blade
• React
• Vue
• Angular
• Vanilla JavaScript
• Mobile applications
• Any frontend capable of communicating with your backend API

Features

• Unified payment gateway contract.
• Runtime gateway selection through driver().
• Stripe card payments using PaymentIntents.
• Paymob card payments using a hosted iframe.
• Paymob mobile-wallet payments.
• Payment retries.
• Full and partial refunds.
• Stripe signed webhook verification.
• Paymob HMAC callback verification.
• Local customer persistence.
• Local transaction persistence.
• Local refund persistence.
• Normalized PaymentStatus enum.
• Minor-unit monetary storage.
• Raw gateway responses stored in meta_data.
• Gateway-specific API services.
• Gateway-specific webhook handlers.
• Repository-based persistence.
• DTOs and value objects for important boundaries.
• Optional Stripe Blade card-payment component.
• Extensible architecture for adding additional gateways.

Requirements

The package requirements are defined by composer.json.

The package targets the current development version documented by this README.

Installation

Install the package through Composer:

Laravel package discovery automatically registers the package service provider and facade.

Publish Configuration

Publish Views and Frontend Assets

Publish Migration Files

Run Migrations

The package provides three main tables:

Configuration

The package configuration is available at:

The gateway registry is available at:

Environment Variables

Stripe

Paymob

Gateway Registry

Gateways are registered through:

Example:

The manager and factory use this registry to resolve the requested gateway.

Quick Start

Selecting a Gateway

Use Ma\Payment\Facades\MaPayment to select a gateway:

You can then call the common gateway operations:

The same architecture is used for Paymob:

Payment Data

A payment request contains the payment amount, currency, customer information, and gateway-specific payment information.

Example:

Amounts

Application-facing payment amounts use major units:

The package converts monetary values to minor units for gateway communication and persistence:

Transactions store amounts in minor units.

Payment Flow

The general payment architecture is:

The common payment workflow is implemented by BaseGateway.

Conceptually:

Gateway implementations provide the provider-specific operations while the shared workflow remains in the base gateway.

Payment Status

The package normalizes gateway-specific statuses into:

Supported states include:

Gateway-specific status values are mapped into these common states.

For example:

This allows the application to work with a common status model regardless of the selected gateway.

Stripe

Capabilities

Stripe Card Payment

Stripe card payments use Stripe PaymentIntents.

The frontend creates a Stripe PaymentMethod and sends its ID to your backend.

The backend then:

1. Validates the payment request.
2. Creates or updates the local customer.
3. Creates the Stripe customer when required.
4. Creates the PaymentIntent.
5. Confirms the PaymentIntent.
6. Persists the local transaction.
7. Returns the payment result.

Stripe Blade Card Component

The package provides an optional Blade component for Stripe card payments.

It is not required to use the Stripe gateway.

View:

The component uses Stripe Elements and Stripe.js to collect the customer's card details.

Publishing the Component

The published JavaScript asset is available under:

Component Example

Component Properties

The component:

1. Mounts Stripe Elements.
2. Collects card information.
3. Creates a Stripe PaymentMethod.
4. Sends the PaymentMethod ID to your backend.
5. Displays payment errors.
6. Redirects after successful payment.

Stripe With Other Frontends

The Stripe Blade component is only a convenience feature.

You can use the same backend API with:

React Example

The frontend flow is:

For example, a React or Vue application can create a Stripe PaymentMethod and send its ID to a Laravel endpoint that calls:

The package does not require the frontend to use Blade.

Stripe Retry

Failed Stripe payments can be retried by re-confirming the existing PaymentIntent with a new PaymentMethod.

The retry operation remains gateway-specific while being exposed through the common gateway contract.

Paymob

Capabilities

Paymob Card Payment

Paymob card payments use a hosted checkout iframe.

The payment flow is:

A new local transaction is initially stored as:

The callback later determines the final transaction status through paymob webhook handler.

Paymob Wallet Payment

Wallet payments are selected using:

Example:

The customer's phone number is used as the wallet identifier.

The Paymob wallet integration uses:

The resulting payment response contains the provider redirect URL.

Your application can redirect the customer to that URL.

Paymob Callback Verification

Paymob callbacks must be verified before updating a transaction.

Example:

The verification flow is:

The callback signature is verified using the configured:

An invalid signature must prevent the transaction from being processed.

Applications should expose their own callback route and delegate the callback payload to the gateway.

Webhooks and Callbacks

The package does not register application routes or controllers automatically.

Your Laravel application owns the HTTP endpoint.

The application then delegates the payload to the appropriate gateway handler.

Stripe Webhook

Example:

The handler verifies the Stripe signature using:

Handled events include:

Unhandled events return an appropriate unhandled result rather than being processed as payment events.

Refund Webhook Race Condition and UpdateRefundTransactionJob

Stripe can deliver related webhook events independently. The package therefore cannot assume that the refund child transaction created from refund.created will always exist before the charge.refunded event attempts to update it:

Because webhook processing can overlap, or events can arrive in an unexpected order, charge.refunded may attempt to update the refund transaction before refund.created has created (or committed) the corresponding record.

How the Package Solves It

When the charge.refunded branch of the Stripe webhook flow (StripeGateway::verify()) updates the parent transaction and a refund_id is present, the package dispatches Ma\Payment\Jobs\UpdateRefundTransactionJob to update the refund transaction record asynchronously:

The Job (src/Jobs/UpdateRefundTransactionJob.php) implements Illuminate\Contracts\Queue\ShouldQueue and works as follows:

• It attempts to find the refund transaction through RefundTransactionRepository::getRefundTransaction() (which also locks the row with lockForUpdate()).
• If the refund transaction is temporarily unavailable (for example, because refund.created has not yet created it), the Job throws Ma\Payment\Exceptions\RefundTransactionNotFoundException.
• Because the exception is thrown from a queued Job, Laravel retries the Job instead of permanently losing the update.
• The Job controls its retry behavior with the actual configuration from the code:
  • $tries = 5
  • backoff(): [2, 4, 5, 6, 7] (seconds between attempts)

The retry delay gives the refund.created webhook time to create the refund transaction before the update is attempted again. Once the refund transaction exists, the Job updates its refund_type attribute and completes.

Flow

Normal order:

If the refund transaction does not yet exist:

Queue Worker Requirement

Because UpdateRefundTransactionJob implements ShouldQueue, the consuming Laravel application must have a queue worker running for the Job to be processed:

The package provides and dispatches the Job, but the Laravel application using the package is responsible for configuring its queue connection and running the queue worker.

Package Installation Context

UpdateRefundTransactionJob is included inside the package (under the Ma\Payment\Jobs namespace) and does not need to be published or copied into the consuming application's app/Jobs directory. The consuming application simply installs the package and runs its normal Laravel queue worker.

CSRF

If the webhook endpoint is registered under a CSRF-protected route group, configure the endpoint appropriately for your application.

For example:

Only disable CSRF protection for the webhook endpoint where appropriate.

Paymob Callback

Paymob callbacks are handled by your application's callback route.

Example:

The gateway verifies the HMAC before processing the transaction.

Transaction Processing

Transactions are stored in:

A transaction contains information such as:

• Local transaction ID
• Customer ID
• Gateway
• Gateway reference
• Amount
• Remaining refundable amount
• Currency
• Status
• Gateway metadata

Gateway responses are stored in:

This allows applications to retain the original gateway response for reconciliation and debugging.

Listing & Filtering Transactions

The package provides transaction listing and filtering through every gateway. Both StripeGateway and PaymobGateway implement these methods, which are declared on the Ma\Payment\Interfaces\PaymentGatewayInterface contract:

Retrieving Transactions

Retrieve transactions through a resolved gateway driver:

Filtering by Customer

getCustomerTransactions() returns the transactions belonging to a specific application user (matched through the package's local payment_customers mapping):

If the user has no gateway customer mapping, a Ma\Payment\Exceptions\CustomerNotFoundException is thrown.

Available Filters

The only filter parameter implemented is status (an optional ?string $status applied as an exact-match where('status', $status) condition on the payment_transactions table).

Supported status values are the values of the Ma\Payment\Enums\PaymentStatus enum:

Passing a status that does not exist in the database simply returns an empty collection; the package does not validate the status value against the enum.

Note: Filters by gateway, date range, order ID, or gateway reference are not exposed through getTransactions() / getCustomerTransactions(). (Repository lookup helpers such as getTransactionByRef(), getTransactionByOrderId(), and getTransactionByGateway() exist for internal webhook/callback processing, but they are single-record lookups and are not part of the public listing API.)

Filtering by Multiple Criteria

Combining multiple filters is not supported by the listing methods — the only supported parameter is the single optional status filter. To filter by multiple criteria, retrieve the collection and narrow it in your application:

Returned Structure

Both methods return an Illuminate\Database\Eloquent\Collection of Ma\Payment\Models\PaymentTransaction models. No pagination is implemented — the underlying query uses ->get(), so the full result set is loaded.

Each model exposes the following attributes (the model's $fillable fields):

The model also provides helpers and relations:

• pounds(): float — converts minor_amount to major units.
• customer() — belongs-to relation to Ma\Payment\Models\PaymentCustomer.
• refundedPayments() — has-many relation to Ma\Payment\Models\RefundedPaymentTransaction.

Example:

Refunds

Both Stripe and Paymob expose refunds through:

Example:

The amount is provided in major units.

For example:

The package prevents refunds that exceed the remaining refundable amount.

Refund Rules

The package validates:

1. The transaction exists.
2. The requested refund does not exceed the remaining amount.
3. The gateway transaction reference matches the local transaction.
4. The refund is persisted successfully.
5. The remaining refundable amount is updated.

Refund records are stored in:

Partial Refunds

Partial refunds can be performed multiple times until the remaining amount reaches zero.

Example:

The transaction status changes from:

to:

and finally:

Capture

Capture is currently not supported.

There is no capture operation in:

Stripe PaymentIntents used by the package are confirmed using the configured payment flow rather than exposing a separate authorization/capture operation.

Void

Void is currently not supported.

The package does not expose an authorization-only → void lifecycle.

Paymob refunds are treated as refunds rather than as a separate void operation.

Retry Payments

Retry behavior is gateway-specific but exposed through the common API:

Stripe

Stripe retries the PaymentIntent using a new PaymentMethod.

Paymob

Paymob creates a new payment attempt and returns a new payment link for the faild local transaction.

Retry operations should only be allowed for transaction states supported by the gateway implementation.

Gateway Support Matrix

Error Handling

Package exceptions are located under:

Common exceptions include:

Example:

Stripe-specific SDK exceptions may also be exposed when the Stripe API rejects a request.

For example:

Frontend Integration

The package does not require a specific frontend framework.

Stripe

The frontend creates the Stripe PaymentMethod and sends the ID to your backend.

Paymob

Paymob provides the payment interface through the provider:

Your application only needs to redirect or embed the returned payment URL.

Architecture

The package uses a layered and extensible gateway architecture.

The shared payment workflow is implemented by:

Design Patterns

The package uses several established design patterns.

Facade

Provides a convenient entry point for the package.

Factory

Creates gateway implementations from the driver registry.

Strategy

Allows Stripe, Paymob, and future gateways to be interchangeable.

Template Method

Defines the shared payment workflow while allowing gateways to implement gateway-specific operations.

Repository

Repositories isolate persistence logic from gateway logic.

Examples:

DTO

DTOs define structured boundaries between application, gateway, and persistence layers.

Examples:

Value Objects

The package uses value objects for validated primitives such as:

Core Components

PaymentGatewayManager

Responsible for selecting a gateway driver.

PaymentGatewayFactory

Responsible for resolving a configured gateway implementation.

The factory reads:

and resolves the gateway through Laravel's service container.

PaymentGatewayInterface

The gateway contract defines the common gateway API.

Typical operations include:

Gateway implementations may support different capabilities while maintaining the common contract.

BaseGateway

BaseGateway contains the shared payment orchestration.

The main payment workflow is implemented by:

The method coordinates:

Gateway-specific classes should not duplicate this common workflow.

Data Transfer Objects

PaymentRequestDTO

Represents validated payment input.

It sits at the boundary between:

It handles concepts such as:

• Amount
• Currency
• Customer
• Source
• Payment method

PaymentTransactionDTO

Represents the data required to persist a payment transaction.

It sits at the boundary between:

Gateway implementations map provider responses into this DTO before passing the data to the repository.

Value Objects

Money

Represents monetary values and provides controlled conversion between major and minor units.

Example:

Financial amounts should be persisted using integer minor units rather than floating-point database values.

UserEmail

Represents a validated customer email address.

Repositories

The package uses repositories to isolate database persistence.

TransactionRepository

Handles payment transaction persistence and queries.

PaymentCustomerRepository

Handles gateway customer mappings.

RefundTransactionRepository

Handles refund transaction persistence.

Database operations involving concurrent transaction updates use appropriate row locking where required.

Database Relationships

The main relationships are:

A customer can have multiple payment transactions.

A payment transaction can have multiple refund records.

Adding a New Gateway

Adding a new gateway should not require modifying the generic payment workflow.

For example, to add a Tap gateway:

1. Create the Gateway

2. Inject the Gateway API Service

3. Implement the Gateway API Call

4. Map the Gateway Response

Build a:

from the provider response.

Gateway-specific statuses should be normalized through the package status mapping.

5. Register the Driver

Add the gateway to:

The manager and factory do not need gateway-specific changes.

6. Add Configuration

Add provider credentials and gateway-specific configuration to:

Use environment variables for secrets and credentials.

7. Add Webhook Handling

If the gateway supports webhooks:

should be responsible for:

1. Signature verification.
2. Event parsing.
3. Event identification.
4. Transaction lookup.
5. Status mapping.
6. Safe transaction updates.

8. Add Tests

A new gateway should have tests covering:

• Successful payment.
• Failed payment.
• Invalid payment data.
• Verification.
• Invalid signature.
• Duplicate callback.
• Refund.
• Partial refund.
• Over-refund.
• Gateway-reference mismatch.
• Retry where supported.

9. Update Documentation

Add the gateway to:

• Supported Gateways.
• Gateway Support Matrix.
• Gateway-specific documentation.
• Configuration documentation.

Gateway Implementation Rules

When implementing a new gateway:

Do

• Extend BaseGateway.
• Implement PaymentGatewayInterface.
• Keep API communication inside a gateway-specific API service.
• Keep webhook parsing inside a gateway-specific webhook handler.
• Reuse the existing repositories.
• Reuse PaymentRequestDTO where possible.
• Build PaymentTransactionDTO for persistence.
• Normalize gateway statuses.
• Store monetary values in minor units.
• Add automated tests.

Do Not

• Duplicate executePayment().
• Put gateway API calls inside repositories.
• Put gateway-specific API logic in BaseGateway.
• Modify generic payment logic for every new gateway.
• Store secrets directly in source code.
• Silently pretend unsupported operations are supported.

Testing

The package is prepared for automated testing through PHPUnit and Composer. The complete testing infrastructure — the test runner, the Composer command, a local pre-push protection hook, and a GitHub Actions CI workflow — is already configured in this repository. However, the actual test cases have not been implemented yet, so no automated test coverage currently exists.

Automated Testing Infrastructure

1. PHPUnit

• PHPUnit is configured as a development dependency (phpunit/phpunit: ^10.0 in require-dev).
• composer test is the standard command for running the test suite (it invokes phpunit).
• phpunit.xml defines two test suites: Unit (tests/Unit) and Feature (tests/Feature).
• Test classes are autoloaded through the Tests\ PSR-4 mapping (autoload-dev in composer.json).

Note: These suites are currently empty. The presence of this configuration does not imply existing test coverage.

2. Local Pre-Push Protection

A Git pre-push hook is provided in the repository at:

The hook performs the following on every push:

1. Runs composer test.
2. If the test command fails (non-zero exit code), the push is rejected.
3. If the test command succeeds, the push proceeds.

This is a preventive development workflow mechanism. It guarantees that pushes are only made after the test command passes locally. It does not represent existing test coverage — the hook simply executes whatever the test suite contains at the time.

3. GitHub Actions CI

A GitHub Actions workflow is configured at:

It automatically executes the test command (composer test) on:

• Pushes to the main branch.
• Pull Requests targeting the main branch.

The workflow runs on ubuntu-latest and uses a version matrix to validate package compatibility across the supported Laravel/PHP combinations:

Testing multiple Laravel versions ensures the package works across all Laravel versions it claims to support, rather than only the one used during development. The matrix is configured with fail-fast: false, so all combinations run even if one fails; however, a failed matrix job causes the overall CI workflow to fail, surfacing incompatibilities in the Checks tab.

Each matrix job installs the matrix-specific Laravel version, installs dependencies, and runs the test suite.

4. Pull Request / Branch Protection

On the GitHub side, Pull Requests targeting a protected branch can be combined with required status checks:

• The CI workflow runs automatically for every Pull Request.
• The branch is configured (in the repository settings) to require the CI check, a Pull Request cannot be merged while the CI workflow is failing.
• Failed required checks block the merge regardless of approvals.

This provides a second layer of protection that remains effective even if someone bypasses the local pre-push hook (for example, by pushing with --no-verify or pushing from a machine where the hook is not activated).

5. Protection Flow

6. Current Testing Status

What Should Be Tested?

Payment

Test:

• Successful payment.
• Failed payment.
• Invalid payment data.
• Customer creation/update.
• Transaction persistence.
• Gateway response mapping.
• Payment status mapping.

Webhooks and Callbacks

Test:

• Valid signature.
• Invalid signature.
• Missing signature.
• Tampered payload.
• Unknown transaction.
• Already processed transaction.
• Supported events.
• Unsupported events.

For Stripe, test every event explicitly handled by the package.

For Paymob, test both valid and invalid HMAC callbacks.

Refunds

Test:

• Full refund.
• Partial refund.
• Multiple partial refunds.
• Over-refund rejection.
• Unknown transaction.
• Gateway/local reference mismatch.
• Correct remaining amount.
• Correct final transaction status.

Retry

Test:

• Valid retry.
• Retry of failed transaction.
• Retry of pending transaction where supported.
• Retry of an already completed transaction.
• Gateway API failure.

Contributing

Contributions are welcome.

When adding or modifying functionality:

1. Follow the existing architecture.
2. Keep gateway-specific code inside its gateway directory.
3. Avoid changing the generic payment workflow unnecessarily.
4. Add or update tests.
5. Run the complete test suite.
6. Update the documentation.
7. Update the gateway support matrix when capabilities change.
8. Preserve backward compatibility.

Project Structure

A simplified package structure:

Architecture Principles

The package follows several important principles:

Single Responsibility

Different responsibilities are separated:

• Gateway
• API Service
• Webhook Handler
• Repository
• DTO
• Value Object

Open/Closed Principle

A new gateway can be added without changing the generic payment workflow.

Liskov Substitution

Gateway implementations follow the common gateway contract.

Dependency Inversion

Infrastructure dependencies are injected through abstractions where appropriate.

Separation of Concerns

Gateway-specific API behavior remains isolated from:

• Persistence.
• Generic payment orchestration.
• DTO definitions.
• Application integration.

Author

License

MIT © Mohamed Allam