README

A multi-gateway payment integration package for Laravel. Provides a unified API to initiate payments, store transactions, handle gateway callbacks, and query payment state on any Eloquent model — without coupling your application to a specific provider.

Requirements
Installation
Configuration
- Environment Variables
- Publishing Config
Database
Supported Gateways
Basic Usage
- Creating a Payment
- Handling the Callback
PaymentPayload DTO
- Redirect URL Placeholders
CheckoutResponse DTO
PaymentResponse DTO
The Invoiceable Contract
HasTransactions Trait
Transaction Model
Adding a Custom Gateway
Gateway Reference
- MyFatoorah
- Stripe

Requirements

Dependency	Version
PHP	>= 8.2
Laravel	>= 10
myfatoorah/laravel-package	^2.1
stripe/stripe-php	^13.0

Installation

Install via Composer:

composer require mosamy/payment

Laravel's auto-discovery will register Mosamy\Payment\PaymentServiceProvider automatically. No manual provider registration is needed.

Configuration

Publishing Config

Publish the configuration file to your application:

php artisan vendor:publish --tag=payment-config

This creates config/payment.php in your application which you can freely modify.

Environment Variables

Add the following to your .env file according to which gateways you use:

# Active default gateway: myfatoorah | stripe
PAYMENT_DEFAULT=myfatoorah

# Comma-separated list of enabled gateways (defaults to PAYMENT_DEFAULT if omitted)
ACTIVATED_GATEWAYS=myfatoorah,stripe

# Default currency (ISO 4217 — defaults to SAR if omitted)
PAYMENT_CURRENCY=SAR

# ── MyFatoorah ────────────────────────────────────────────────────────────────
MYFATOORAH_API_KEY=your-api-key-here
MYFATOORAH_TEST_MODE=false
MYFATOORAH_COUNTRY_ISO=SAU          # e.g. SAU, KWT, ARE, QAT, BHR, OMN, EGY

# ── Stripe ────────────────────────────────────────────────────────────────────
STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...

Full Config File

// config/payment.php
return [

    /*
    |--------------------------------------------------------------------------
    | Default Gateway
    |--------------------------------------------------------------------------
    | The gateway used when no gateway is explicitly specified.
    | Must match a key under "gateways".
    */
    'default' => env('PAYMENT_DEFAULT'),

    /*
    |--------------------------------------------------------------------------
    | Active Gateways
    |--------------------------------------------------------------------------
    | Comma-separated list of enabled gateway keys. Only listed gateways are
    | registered as valid callback route parameters.
    */
    'active' => explode(',', env('ACTIVATED_GATEWAYS', env('PAYMENT_DEFAULT'))),

    /*
    |--------------------------------------------------------------------------
    | Default Currency
    |--------------------------------------------------------------------------
    | Used as the fallback currency when PaymentPayload is constructed without
    | an explicit currency value.
    */
    'currency' => env('PAYMENT_CURRENCY', 'SAR'),

    /*
    |--------------------------------------------------------------------------
    | Transaction Statuses
    |--------------------------------------------------------------------------
    | The allowed values for the transaction status column and PaymentResponse.
    */
    'statuses' => ['pending', 'paid', 'failed', 'refunded', 'cancelled'],

    /*
    |--------------------------------------------------------------------------
    | Gateways
    |--------------------------------------------------------------------------
    | Each entry maps a friendly name to its gateway class and its own config
    | block. You may add custom gateways here.
    */
    'gateways' => [

        'myfatoorah' => [
            'class'  => \Mosamy\Payment\Gateways\MyFatoorah::class,
            'config' => [
                'api_key'     => env('MYFATOORAH_API_KEY'),
                'test_mode'   => env('MYFATOORAH_TEST_MODE', false),
                'country_iso' => env('MYFATOORAH_COUNTRY_ISO', 'SAU'),
            ],
        ],

        'stripe' => [
            'class'  => \Mosamy\Payment\Gateways\Stripe::class,
            'config' => [
                'key'    => env('STRIPE_KEY'),
                'secret' => env('STRIPE_SECRET'),
            ],
        ],

    ],
];

Database

Run the package migrations to create the transactions table:

php artisan migrate

The transactions table schema:

Column	Type	Notes
id	bigint (PK)
reference	string (unique)	Invoice / order reference, indexed
gateway	string	Gateway key (e.g. `myfatoorah`), indexed
amount	decimal(12,2)
currency	string	ISO 4217 code (e.g. `SAR`, `USD`)
status	enum	`pending`, `paid`, `failed`, `refunded`, `cancelled`
meta	json nullable	Customer data and extra fields
response	json nullable	Raw gateway responses stored per stage
payable_type	string nullable	Polymorphic owner type
payable_id	bigint nullable	Polymorphic owner id
created_at	timestamp
updated_at	timestamp

The allowed status values are driven by config('payment.statuses'), so they stay in sync if you extend that list.

Supported Gateways

Gateway	Status	Key
MyFatoorah	Full support	`myfatoorah`
Stripe	Full support	`stripe`

Basic Usage

Creating a Payment

The main entry point is the Payment class. Call Payment::gateway() with an optional gateway key (falls back to PAYMENT_DEFAULT), then pass a PaymentPayload to create():

use Mosamy\Payment\Payment;
use Mosamy\Payment\DTO\PaymentPayload;

$payload = new PaymentPayload(
    id: (string) $order->id,           // unique identifier for this invoice
    amount: $order->total,
    currency: 'SAR',
    customer: [
        'name'  => $user->name,
        'email' => $user->email,
        'phone' => $user->phone,        // MyFatoorah requires 05XXXXXXXX format
    ],
    items: [
        ['name' => 'Product A', 'quantity' => 2, 'unit_cost' => 50.00],
    ],
    meta: [
        'payment_method_id' => 2,       // required by MyFatoorah; get list via their API
    ],
    redirectUrl: route('orders.show', $order),
);

$response = Payment::gateway('myfatoorah')  // or omit to use default
    ->payable($order)                        // optional: links transaction to any Eloquent model
    ->create($payload);

if ($response->success) {
    return redirect($response->redirectUrl);
}

// Handle failure
return back()->withErrors($response->response['message'] ?? 'Payment initiation failed.');

->payable($model) is optional. When provided, the transaction row is linked to that model via a polymorphic relation (payable_type / payable_id).

Handling the Callback

The package automatically registers a callback route:

GET /payments/callback/{gateway}/{transaction}

Named: mosamy.payment.callback

The gateway redirects the user back to this URL after payment. The controller resolves the Transaction model via route-model binding, delegates to the correct gateway's handleCallback(), and redirects the user to PaymentResponse::$redirectUrl (or / if none is set).

You do not need to define this route yourself. It is loaded automatically by the service provider.

PaymentPayload DTO

use Mosamy\Payment\DTO\PaymentPayload;

new PaymentPayload(
    id: string,            // Required. Unique invoice identifier (e.g. order id).
    amount: float,         // Required. Amount in the given currency.
    reference: ?string,    // Optional. Defaults to "REF-{id}".
    currency: ?string,     // Optional. Defaults to config('payment.currency') — e.g. 'SAR'.
    items: ?array,         // Optional. Line items for the invoice.
    customer: ?array,      // Optional (required by some gateways). See gateway docs.
    meta: ?array,          // Optional. Extra data stored on the transaction + gateway.
    redirectUrl: ?string,  // Optional. Static URL or a placeholder template — see below.
);

Redirect URL Placeholders

When redirectUrl contains placeholders, they are resolved right after the local transaction is created and before the gateway checkout is initiated. This lets you build dynamic URLs based on data that only exists once the transaction row is persisted.

Placeholder	Replaced with
`{transaction_id}`	The auto-incremented transaction id
`{transaction_reference}`	The transaction reference string
`{payment_id}`	The `id` value from `PaymentPayload`

Example — redirect to a transaction detail page without knowing the id upfront:

// No model involved, just a raw Payment::gateway() call.
$payload = new PaymentPayload(
    id: 'INV-45',
    amount: 120.50,
    redirectUrl: '/transactions/{transaction_id}',
);

$response = Payment::gateway()->create($payload);
// If the created transaction id is 981, the callback will redirect to /transactions/981

Example — redirect from an Invoiceable model:

public function toPaymentPayload(?array $meta = []): PaymentPayload
{
    return new PaymentPayload(
        id: (string) $this->id,
        amount: $this->total,
        redirectUrl: "/invoices/{$this->id}",   // static — model id is known here
    );
}

The resolved URL is persisted back into response->invoice->redirectUrl on the transaction, so the callback controller always reads the correct final URL.

CheckoutResponse DTO

Returned by Payment::gateway()->create():

$response->success        // bool    — whether the checkout session was initiated
$response->transactionId  // ?string — the local transaction id
$response->redirectUrl    // ?string — gateway checkout URL to send the customer to
$response->response       // array   — raw gateway response
$response->toArray()      // array   — all fields as an array

When success is true, both redirectUrl and transactionId are guaranteed to be non-null (enforced in the constructor).

PaymentResponse DTO

Returned by Payment::gateway()->handleCallback():

$response->success      // bool    — whether the payment was confirmed
$response->status       // string  — final transaction status written to the database
$response->redirectUrl  // ?string — where to redirect the user after callback
$response->response     // array   — raw gateway callback data

status must be one of the values defined in config('payment.statuses') (pending, paid, failed, refunded, cancelled). An InvalidArgumentException is thrown if an invalid value is provided.

The Invoiceable Contract

Implement Mosamy\Payment\Contracts\Invoiceable on any model that needs to be converted to a PaymentPayload:

use Mosamy\Payment\Contracts\Invoiceable;
use Mosamy\Payment\DTO\PaymentPayload;

class Order extends Model implements Invoiceable
{
    public function toPaymentPayload(?array $meta = []): PaymentPayload
    {
        return new PaymentPayload(
            id: (string) $this->id,
            amount: $this->total,
            currency: $this->currency,
            customer: [
                'name'  => $this->user->name,
                'email' => $this->user->email,
                'phone' => $this->user->phone,
            ],
            meta: array_merge([
                'payment_method_id' => 2,
            ], $meta),
        );
    }
}

When your model also uses the HasTransactions trait, you can call $order->pay() directly (see below).

HasTransactions Trait

Add HasTransactions to any Eloquent model that initiates or owns payments:

use Mosamy\Payment\Traits\HasTransactions;
use Mosamy\Payment\Contracts\Invoiceable;

class Order extends Model implements Invoiceable
{
    use HasTransactions;

    // Must implement toPaymentPayload() when using ->pay()
    public function toPaymentPayload(?array $meta = []): PaymentPayload { ... }
}

Relations

// All transactions belonging to this model
$order->transactions;   // Collection<Transaction>

// The latest transaction
$order->transaction;    // ?Transaction

Computed Attributes

$order->is_paid;              // bool — latest transaction status is 'paid'
$order->has_pending_payment;  // bool — latest transaction status is 'pending'

// Sum of all transactions with the given status (default: 'paid')
$order->totalAmount();
$order->totalAmount('failed');

Scopes

// Eager-load both relations at once
Order::withTransactions()->get();

// Filter models that have at least one transaction with the given status
Order::whereHasTransactions()->get();
Order::whereHasTransactions('failed')->get();

// Add a transactions_sum_amount column (filtered by status)
Order::withTotalAmount()->get();
Order::withTotalAmount('refunded')->get();

Quick Pay

When your model implements Invoiceable, you can initiate a payment in one call:

// Uses default gateway
$response = $order->pay();

// Specify gateway
$response = $order->pay(gateway: 'myfatoorah');

// Pass extra meta merged into toPaymentPayload()
$response = $order->pay(gateway: 'myfatoorah', meta: ['payment_method_id' => 6]);

pay() calls Payment::gateway($gateway)->payable($this)->create($this->toPaymentPayload($meta)) internally.

Transaction Model

Mosamy\Payment\Models\Transaction

Method / Attribute	Description
`$transaction->status`	`pending` \| `paid` \| `failed` \| `refunded` \| `cancelled`
`$transaction->gateway`	Gateway key string
`$transaction->amount`	Decimal amount
`$transaction->currency`	ISO 4217 currency code
`$transaction->reference`	Invoice reference
`$transaction->meta`	Array of stored metadata (includes `customer`)
`$transaction->response`	Array with `invoice`, `checkout`, and `callback` sub-keys
`$transaction->payable`	Related model (polymorphic, nullable)
`$transaction->callbackUrl`	Auto-generated route URL for this transaction

Adding a Custom Gateway

Create a class that extends Mosamy\Payment\Contracts\Gateway:

namespace App\Payments;

use Mosamy\Payment\Contracts\Gateway;
use Mosamy\Payment\DTO\CheckoutResponse;
use Mosamy\Payment\DTO\PaymentPayload;
use Mosamy\Payment\DTO\PaymentResponse;
use Mosamy\Payment\Models\Transaction;

class MyCustomGateway extends Gateway
{
    public function create(PaymentPayload $payload, Transaction $transaction): CheckoutResponse
    {
        // Call external API, get redirect URL ...

        return new CheckoutResponse(
            success: true,
            transactionId: (string) $transaction->id,
            redirectUrl: 'https://pay.example.com/invoice/...',
            response: [],
        );
    }

    public function handleCallback(array $payload, Transaction $transaction): PaymentResponse
    {
        // Verify signature, check status ...

        return new PaymentResponse(
            success: true,
            status: 'paid',
            redirectUrl: $transaction->response['invoice']['redirectUrl'] ?? '/',
            response: $payload,
        );
    }
}

'gateways' => [
    // ...
    'myprovider' => [
        'class'  => \App\Payments\MyCustomGateway::class,
        'config' => [
            'api_key' => env('MYPROVIDER_API_KEY'),
        ],
    ],
],

Set your env:

PAYMENT_DEFAULT=myprovider

That's it. The route constraint, transaction creation, and callback flow are all handled automatically.

Gateway Reference

MyFatoorah

Required customer fields:

Field	Format	Example
`name`	string	`"Ahmed Al-Zaidi"`
`email`	valid email	`"a@example.com"`
`phone`	`05XXXXXXXX`	`"0512345678"`

Required meta fields:

Field	Type	Description
`payment_method_id`	integer	Payment method ID from MyFatoorah API

Notes:

country_iso controls which regional MyFatoorah endpoint is used.
MobileCountryCode is currently hardcoded to +966. If your application targets other regions, override by extending the MyFatoorah gateway class and overriding payload().
Callback uses the same URL for success and error redirects. MyFatoorah appends ?paymentId=... on success.

Stripe