elfarmawy/laravel-fawaterk

Production-ready Laravel SDK for the Fawaterak payment gateway

v1.1.0 2026-05-29 22:31 UTC

Requires

• php: ^8.2
• illuminate/http: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

Requires (Dev)

• nunomaduro/larastan: ^2.0|^3.0
• orchestra/testbench: ^8.0|^9.0|^10.0
• pestphp/pest: ^2.0|^3.0
• pestphp/pest-plugin-laravel: ^2.0|^3.0
• phpstan/phpstan: ^1.10|^2.0

MIT

• Tarek Hesham

• payment
• sdk
• laravel
• payment-gateway
• api-wrapper
• fawaterak
• elfarmawy

README

A modern, strongly-typed Laravel SDK for the Fawaterk payment gateway.

Built with DTOs, Enums, Fluent Builders, Tokenization Support, Secure Webhooks, and a developer-first architecture.

Introduction

Laravel Fawaterk is a modern Laravel SDK designed to simplify integration with the Fawaterk payment gateway while maintaining a clean and strongly-typed developer experience.

Unlike traditional payment wrappers that rely heavily on arrays and undocumented payloads, this package provides:

• Strongly-typed DTOs
• Immutable request & response objects
• Enum-driven APIs
• Fluent builders
• IDE-friendly autocompletion
• Secure webhook verification
• Laravel-native architecture
• SOLID & DDD-inspired design

The package is intentionally designed to feel natural inside Laravel applications while remaining framework-friendly and easy to extend.

Features

• Invoice creation and payment verification
• Seamless integration for Cards, Installments, Mobile Wallets, Meeza, Fawry, Aman, and Basata.
• Payment methods retrieval
• Card tokenization support
• Typed DTO request & response objects
• Fluent request builders
• Secure HMAC webhook verification
• Immutable readonly objects
• Clean architecture
• Laravel Facade support
• PHPStan-friendly
• Pest testing support
• Laravel 10, 11, 12, and 13 support

Table of Contents

• Requirements

• Installation

• Configuration

• Quick Start

• Invoices

  • Create Invoice
  • Get Invoice Data
  • Verify Paid Invoice

• Gateway Operations

  • Get Payment Methods
  • Initialize Payment

• Tokenization

  • Create Token Screen
  • Pay With Token
  • Delete Token

• Webhooks

• Error Handling

• Testing

• Architecture

• Security

• Contributing

• Changelog

• License

Requirements

Dependency	Version
PHP	8.2+
Laravel	10.x, 11.x, 12.x, 13.x

Installation

You can install the package via Composer:

composer require elfarmawy/laravel-fawaterk

Laravel will automatically register the service provider and facade.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag="fawaterk-config"

Add your credentials to the .env file:

FAWATERK_API_KEY=your_api_key_here

FAWATERK_MODE=staging

Available modes:

• staging
• production

Quick Start

Create an invoice in seconds using the fluent builder API.

use ElFarmawy\Fawaterk\Facades\Fawaterk;
use ElFarmawy\Fawaterk\Enums\Currency;
use ElFarmawy\Fawaterk\Data\Invoices\Requests\CreateInvoiceRequest;

$response = Fawaterk::invoices()->create(
    CreateInvoiceRequest::builder()
        ->cartTotal(150)
        ->currency(Currency::EGP)
        ->customer($customer)
        ->cartItems($items)
        ->build()
);

return redirect($response->data->invoiceUrl);

Invoices

Create Invoice

use ElFarmawy\Fawaterk\Facades\Fawaterk;
use ElFarmawy\Fawaterk\Data\Invoices\Requests\CreateInvoiceRequest;
use ElFarmawy\Fawaterk\Data\Invoices\Shared\CustomerData;
use ElFarmawy\Fawaterk\Data\Invoices\Shared\CartItemData;
use ElFarmawy\Fawaterk\Enums\Currency;

$request = CreateInvoiceRequest::builder()
    ->cartTotal(150.50)
    ->currency(Currency::EGP)
    ->customer(
        new CustomerData(
            firstName: 'John',
            lastName: 'Doe',
            email: '[e-mail]',
            phone: '01000000000',
            address: '123 Main St'
        )
    )
    ->cartItems([
        new CartItemData(
            name: 'Product 1',
            price: 100,
            quantity: 1
        ),

        new CartItemData(
            name: 'Product 2',
            price: 50.5,
            quantity: 1
        ),
    ])
    ->build();

$response = Fawaterk::invoices()
    ->create($request);

$invoiceId = $response->data->invoiceId;

$paymentLink = $response->data->invoiceUrl;

Get Invoice Data

$response = Fawaterk::invoices()
    ->find($invoiceId);

Verify Paid Invoice

$verifiedInvoice = Fawaterk::invoices()
    ->verifyPaid($invoiceId);

This method throws a RequestException if the invoice is not paid or does not exist.

Gateway Operations

Get Payment Methods

$methods = Fawaterk::gateway()
    ->paymentMethods();

foreach ($methods as $method) {
    echo $method->name_en;
}

Initialize Payment

use ElFarmawy\Fawaterk\Facades\Fawaterk;
use ElFarmawy\Fawaterk\Data\Gateway\Requests\InitPayRequest;
use ElFarmawy\Fawaterk\Enums\Currency;

$request = new InitPayRequest(
    payment_method_id: 2,
    cartTotal: 100,
    currency: Currency::EGP,
    invoice_number: 'INV-' . time(),
    customer: $customerData,
    cartItems: $cartItems,
    redirectionUrls: $redirectionUrlsData
);

$response = Fawaterk::gateway()
    ->initPay($request);

Depending on the selected payment method, the response will automatically resolve into one of the following DTOs:

• InitPayRedirectResponse
• InitPayFawryResponse
• InitPayMeezaResponse
• InitPayBastaResponse
• InitPayAmanResponse

Tokenization

Create Token Screen

Generate a secure hosted screen for saving customer cards.

use ElFarmawy\Fawaterk\Data\Tokenization\Requests\CreateTokenScreenRequest;
use ElFarmawy\Fawaterk\Data\Invoices\Shared\RedirectionUrlsData;

$request = new CreateTokenScreenRequest(
    customer: $customerData,

    redirectionUrls: new RedirectionUrlsData(
        successUrl: 'https://example.com/success',
        failUrl: 'https://example.com/fail',
        pendingUrl: 'https://example.com/pending'
    )
);

$response = Fawaterk::gateway()
    ->createCardTokenScreen($request);

$url = $response->url;

Pay With Token

use ElFarmawy\Fawaterk\Data\Tokenization\Requests\PayWithTokenRequest;

$request = new PayWithTokenRequest(
    token: 'customer_saved_token',
    cartTotal: 200,
    currency: Currency::EGP,
    customer: $customerData,
    cartItems: $cartItems
);

$response = Fawaterk::gateway()
    ->payWithToken($request);

Delete Token

$response = Fawaterk::gateway()
    ->deleteToken($token);

Webhooks

Laravel Fawaterk provides secure webhook verification and automatic payload parsing into typed DTOs.

Supported webhook events:

• paid
• failed
• canceled
• refund

Example Controller

use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
use ElFarmawy\Fawaterk\Services\FawaterkWebhookService;
use ElFarmawy\Fawaterk\Data\Webhooks\PaidWebhookData;
use ElFarmawy\Fawaterk\Enums\WebhookType;
use ElFarmawy\Fawaterk\Exceptions\WebhookSignatureVerificationException;

class FawaterkWebhookController extends Controller
{
    public function __invoke(
        Request $request,
        FawaterkWebhookService $webhookService
    ) {
        $payload = $request->all();
        $webhookType = $request->query('type') ?? $request->input('type', 'paid');

        try {

            $webhook = $webhookService->verifyAndParse(
                payload: $payload,
                webhookType: WebhookType::from($webhookType)
            );

            if ($webhook instanceof PaidWebhookData) {

                // Handle successful payment

            }

            return response()->json([
                'status' => 'success',
            ]);

        } catch (WebhookSignatureVerificationException $exception) {

            abort(403, 'Invalid webhook signature.');

        }
    }
}

Verify Signature Only

$isValid = $webhookService->verifySignature(
    payload: $payload,
    signature: $signature
);

Error Handling

Laravel Fawaterk maps API responses into typed exceptions.

use ElFarmawy\Fawaterk\Exceptions\ApiException;
use ElFarmawy\Fawaterk\Exceptions\RequestException;
use ElFarmawy\Fawaterk\Exceptions\ValidationException;
use ElFarmawy\Fawaterk\Exceptions\AuthenticationException;

try {

    $response = Fawaterk::invoices()
        ->create($request);

} catch (ValidationException $exception) {

    $errors = $exception->errors;

} catch (AuthenticationException $exception) {

    // Invalid API credentials

} catch (RequestException $exception) {

    // Request processing error

} catch (ApiException $exception) {

    // Generic API exception

}

Testing

Run the test suite:

composer test

or

vendor/bin/pest

Architecture

Laravel Fawaterk follows a layered architecture focused on maintainability, testability, and developer experience.

Application
    ↓
Fawaterk Facade
    ↓
Services
    ↓
DTOs / Builders
    ↓
HTTP Client
    ↓
Fawaterk API

Core Principles

DTO-first Design

Every request and response is represented using strongly-typed DTOs instead of arrays.

Immutable Objects

All DTOs are immutable and readonly where possible.

Enum-driven APIs

Enums are used extensively to prevent invalid payload values.

Thin Service Layer

The package avoids unnecessary business logic and acts as a predictable SDK around the official Fawaterk API.

Laravel-native Experience

The SDK integrates naturally with Laravel conventions, facades, dependency injection, and the HTTP client.

Security

If you discover any security vulnerabilities, please report them responsibly instead of opening a public issue.

Contributing

Contributions are welcome and greatly appreciated.

Please submit a pull request or open an issue for discussion before large changes.

Changelog

Please see CHANGELOG.md for more information about recent changes.

License

The MIT License (MIT).

Please see LICENSE.md for more information.