Payment Gateway PHP Library

A unified, extensible PHP Composer package for integrating with 18 payment gateways (Middle East + Iraq + Europe + International). Built with clean architecture, full API coverage, zero external dependencies, and enterprise-grade security.

---

Table of Contents

• Supported Gateways
• Installation
• Quick Start
• Factory Pattern
• Feature Matrix
• Documentation
• Testing
• Contributing
• License

---

Supported Gateways

MyFatoorah	Paylink	EdfaPay	Tap	ClickPay
Tamara	Thawani	Fatora	Payzaty	Payzah
Stripe	PayPal	NeonPay	AsiaPay	ZainCash
Mollie	Redsys	GoCardless

Gateway	Region	Classes	Key Features	Authentication
MyFatoorah	Middle East	5	Payments, Sessions, Invoices, Customers, Webhooks	API Key (Bearer)
Paylink	Middle East	5	Invoices, Digital Products, Reconciliation, Webhooks	API ID + Secret Key
EdfaPay	Middle East	6	Checkout, Embedded S2S, Apple Pay, Recurring, Refunds	Client Key + Password
Tap	Middle East	7	Charges, Authorize/Void, Refunds, Invoices, Customers, Tokens	Secret Key (Bearer)
ClickPay	Middle East	3	Hosted Page, Auth/Capture/Void/Refund, Tokenization	Server Key
Tamara	Middle East	4	BNPL Checkout, Order Authorize/Capture/Cancel, Refunds	API Token (Bearer)
Thawani	Middle East	4	Checkout Sessions, Payment Intents, Customer Management	Secret + Publishable Key
Fatora	Middle East	4	Checkout, Verify, Refunds, Recurring (Card Tokenization)	API Key
Payzaty	Middle East	3	Secure Checkout, Mada/VISA/MC/Apple Pay/STC Pay	Account No + Secret Key
Payzah	Middle East	3	Hosted Checkout, K-Net/VISA/MC/Apple Pay/Amex	Private Key
NeonPay	Middle East	3	Payments, Refunds, Webhooks (EBIK Key Auth)	EBIK Key (Header)
AsiaPay	Middle East	4	Orders, Refunds, JWT Auth, Webhooks	App Key + Secret (JWT)
ZainCash	Middle East	3	Transactions, JWT HS256 Auth, Webhooks	Merchant ID + Secret (JWT)
Stripe	International	6	Checkout Sessions, Charges, Customers, Refunds, Webhooks	Secret Key (Bearer)
PayPal	International	6	Orders, Captures, Authorizations, Refunds, OAuth 2.0	Client ID + Secret (OAuth)
Mollie	Europe	5	Payments, Refunds, Customers, iDEAL, SEPA, Klarna	API Key (Bearer)
Redsys	Europe	3	Payments, Refunds, 3DES + HMAC-SHA256 Signing	Merchant Key (3DES)
GoCardless	Europe	5	Payments, Mandates, Refunds, Direct Debit, Webhooks	Access Token (Bearer)

79 PHP classes across 18 gateways organized in 3 regions: International/, MiddleEast/, Europe/

---

Installation

composer require azozzalfiras/payment-gateway

Requirement	Version
PHP	>= 8.1
ext-curl	Required
ext-json	Required
ext-mbstring	Required

---

Quick Start

use AzozzALFiras\PaymentGateway\PaymentGateway;
use AzozzALFiras\PaymentGateway\Enums\Gateway;
use AzozzALFiras\PaymentGateway\Enums\PaymentStatus;
use AzozzALFiras\PaymentGateway\DTOs\PaymentRequest;
use AzozzALFiras\PaymentGateway\DTOs\Customer;

// Create gateway from enum
$gateway = PaymentGateway::create(Gateway::TAP->value, [
    'secret_key' => 'sk_test_xxx',
    'testMode'   => true,
]);

// Or use typed static factory
$gateway = PaymentGateway::stripe(['secret_key' => 'sk_test_xxx', 'testMode' => true]);

// Purchase
$response = $gateway->purchase(new PaymentRequest(
    amount:      100.00,
    currency:    'SAR',
    orderId:     'ORDER-001',
    description: 'Premium Plan',
    callbackUrl: 'https://yoursite.com/callback',
    customer:    new Customer(name: 'Ahmed', email: 'ahmed@example.com'),
));

// Redirect customer to payment page
header("Location: {$response->paymentUrl}");

// Check payment status
$status = $gateway->status($response->transactionId);

// Gateway metadata from enum
echo Gateway::TAP->label();           // "Tap Payments"
echo Gateway::TAP->region();          // "MiddleEast"
echo Gateway::TAP->supportsRefund();  // true
echo Gateway::TAP->countries();       // ['KWT', 'SAU', 'ARE', ...]

---

Factory Pattern

use AzozzALFiras\PaymentGateway\PaymentGateway;

// 1. Generic factory — accepts any driver name string
$gateway = PaymentGateway::create('tap', ['secret_key' => '...']);

// 2. Typed static factory — full IDE autocomplete per gateway
$gateway = PaymentGateway::myfatoorah([...]);
$gateway = PaymentGateway::paylink([...]);
$gateway = PaymentGateway::edfapay([...]);
$gateway = PaymentGateway::tap([...]);
$gateway = PaymentGateway::clickpay([...]);
$gateway = PaymentGateway::tamara([...]);
$gateway = PaymentGateway::thawani([...]);
$gateway = PaymentGateway::fatora([...]);
$gateway = PaymentGateway::payzaty([...]);
$gateway = PaymentGateway::payzah([...]);
$gateway = PaymentGateway::stripe([...]);
$gateway = PaymentGateway::paypal([...]);
$gateway = PaymentGateway::neonpay([...]);
$gateway = PaymentGateway::asiapay([...]);
$gateway = PaymentGateway::zaincash([...]);
$gateway = PaymentGateway::mollie([...]);
$gateway = PaymentGateway::redsys([...]);
$gateway = PaymentGateway::gocardless([...]);

// List all 18 available driver names
PaymentGateway::getAvailableDrivers();

---

Feature Matrix

Feature
Purchase	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Status	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Refund	✅	—	✅	✅	✅	✅	—	✅	—	—	✅	✅	✅	✅	—	✅	✅	✅
Recurring	—	—	✅	✅	✅	—	✅	✅	—	—	✅	—	—	—	—	—	—	—
Auth/Capture	✅	—	✅	✅	✅	✅	—	—	—	—	✅	✅	—	—	—	—	—	—
Customer CRUD	✅	—	—	✅	—	—	✅	—	—	—	✅	—	—	—	—	✅	—	—
Direct Debit	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	✅
Webhook	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅

---

Documentation

Document	Description
Gateway Reference	Configuration, code examples, and sub-modules for all 18 gateways
Architecture	Project structure, directory tree, and design principles
Security	Signature verification, input sanitization, and best practices
Webhooks	Unified webhook handling across all gateways
Database Integration	SQL schemas, models, and full payment flow examples
Contributing	How to add gateways, code style, and PR guidelines

---

Testing

composer install
composer test       # PHPUnit
composer analyse    # PHPStan Level 5

Current test results:

• PHPUnit: 135 tests, 281 assertions — all passing
• PHP Lint: all files — zero syntax errors
• PHPStan Level 5: 0 errors

---

Contributing

We welcome pull requests! Whether you're adding a new payment gateway, fixing bugs, or improving documentation.

See CONTRIBUTING.md for detailed guidelines on:

• How to add a new gateway (file structure, contracts, registration)
• Code style (PHP 8.1+, PSR-12, strict types)
• Testing requirements
• PR process

---

License

MIT License — see LICENSE file.

---

Author

AzozzALFiras — GitHub