README

⚠️ IMPORTANT DISCLAIMER

This is NOT an official package from Paymob. This package was created by me to help Laravel developers integrate with Paymob Payout API, as there was no available package at the time of creation.

If Paymob releases an official Laravel package in the future, I am strongly recommend using their official package instead.

This package is provided as-is for the benefit of the developer community and is not affiliated with or endorsed by Paymob.

A comprehensive Laravel wrapper for the Paymob Payout API that provides easy-to-use methods for:

• Token Generation & Management - Automatic OAuth 2.0 token handling with caching
• Instant Cash-In - Disburse money to wallets (Vodafone, Etisalat, Orange, Aman) and bank cards
• Transaction Management - Cancel Aman transactions
• Bulk Transaction Inquiry - Query multiple transaction statuses (with rate limiting)
• Budget Inquiry - Check current balance
• Comprehensive Exception Handling - Specific exceptions for different error scenarios

Requirements

• PHP: ^8.2
• Laravel: ^10.0 || ^11.0 || ^12.0

Installation

You can install the package via composer:

composer require eg-mohamed/paymob-payout

You can publish the config file with:

php artisan vendor:publish --tag="paymob-payout-config"

Configuration

Add the following environment variables to your .env file:

PAYMOB_PAYOUT_ENVIRONMENT=staging
PAYMOB_PAYOUT_CLIENT_ID=your_client_id
PAYMOB_PAYOUT_CLIENT_SECRET=your_client_secret
PAYMOB_PAYOUT_USERNAME=your_username
PAYMOB_PAYOUT_PASSWORD=your_password
PAYMOB_PAYOUT_TIMEOUT=30

Set PAYMOB_PAYOUT_ENVIRONMENT to production when you're ready to go live.

Usage

Basic Usage

use MohamedSaid\PaymobPayout\Facades\PaymobPayout;
use MohamedSaid\PaymobPayout\Enums\IssuerType;
use MohamedSaid\PaymobPayout\Enums\BankTransactionType;

// Generate/refresh token (handled automatically)
$token = PaymobPayout::generateToken();

// Check your current budget
$budget = PaymobPayout::budgetInquiry();
echo $budget->currentBalance; // 888.25 (float)

Cash-In Methods

The package provides three specialized methods for different transaction types, each with specific validation:

Mobile Wallets Cash-In

For Vodafone, Etisalat, Orange, and Bank Wallet transactions:

use MohamedSaid\PaymobPayout\Facades\PaymobPayout;
use MohamedSaid\PaymobPayout\Enums\IssuerType;

$transaction = PaymobPayout::walletCashIn(
    issuer: IssuerType::VODAFONE,
    amount: 100.50,
    msisdn: '01234567890',
    clientReferenceId: '550e8400-e29b-41d4-a716-446655440000' // Optional UUID4
);

echo $transaction->transactionId;
echo $transaction->disbursementStatus; // 'successful', 'pending', 'failed'
echo $transaction->statusDescription;

Aman Cash-In

For Aman transactions with specific requirements:

$transaction = PaymobPayout::amanCashIn(
    amount: 250.00,
    msisdn: '01234567890',
    firstName: 'Ahmed',
    lastName: 'Mohamed',
    email: 'ahmed@example.com',
    clientReference: 'AMAN-2024-001' // Optional unique reference
);

// Aman transactions return a reference number for cash pickup
echo $transaction->referenceNumber;

Bank Card Cash-In

For bank card transactions:

use MohamedSaid\PaymobPayout\Enums\BankTransactionType;
use MohamedSaid\PaymobPayout\Enums\BankCode;

$transaction = PaymobPayout::bankCardCashIn(
    amount: 500.00,
    bankCardNumber: '1234567890123456',
    bankTransactionType: BankTransactionType::CASH_TRANSFER,
    bankCode: BankCode::CIB,
    fullName: 'Ahmed Mohamed',
    clientReference: 'BANK-2024-001' // Optional unique reference
);

// Bank transactions take 2 working days to finalize
echo $transaction->disbursementStatus; // Usually 'pending' initially

Field Validation

Each method includes comprehensive validation specific to the transaction type:

walletCashIn() Validation

• issuer must be VODAFONE, ETISALAT, ORANGE, or BANK_WALLET
• amount must be greater than 0
• msisdn must be 11 digits starting with 01

amanCashIn() Validation

• amount must be greater than 0
• msisdn must be 11 digits starting with 01
• firstName is required and cannot be empty
• lastName is required and cannot be empty
• email must be valid email format

bankCardCashIn() Validation

• amount must be greater than 0
• bankCardNumber must be 13-19 digits
• bankTransactionType is required (enum)
• bankCode is required (enum)
• fullName is required and cannot be empty

Validation Examples

// Wallet validation error
try {
    $transaction = PaymobPayout::walletCashIn(
        issuer: IssuerType::AMAN, // Invalid issuer for wallet method
        amount: 100.0,
        msisdn: '01234567890'
    );
} catch (InvalidArgumentException $e) {
    echo $e->getMessage(); // "Invalid issuer type for wallet cash-in. Use VODAFONE, ETISALAT, ORANGE, or BANK_WALLET"
}

// Aman validation error
try {
    $transaction = PaymobPayout::amanCashIn(
        amount: 100.0,
        msisdn: '01234567890',
        firstName: '', // Empty first name
        lastName: 'Mohamed',
        email: 'ahmed@example.com'
    );
} catch (InvalidArgumentException $e) {
    echo $e->getMessage(); // "First name is required for Aman transactions"
}

Transaction Management

Cancel Aman Transaction

$cancelResult = PaymobPayout::cancelAmanTransaction('607f2a5a-1109-43d2-a12c-9327ab2dca18');

echo $cancelResult->disbursementStatus; // 'successful' if cancelled
echo $cancelResult->referenceNumber;

Bulk Transaction Inquiry

$inquiry = PaymobPayout::bulkTransactionInquiry([
    '607f2a5a-1109-43d2-a12c-9327ab2dca18',
    '708f3b6b-2210-54e3-b23d-a438bc3edb29'
]);

echo $inquiry->count; // Number of transactions returned
foreach ($inquiry->results as $transaction) {
    echo $transaction['transaction_id'];
    echo $transaction['disbursement_status'];
}

// For bank transactions (sends additional bank_transactions parameter)
$bankInquiry = PaymobPayout::bulkTransactionInquiry(
    transactionIdsList: ['transaction-id-1', 'transaction-id-2'],
    bankTransactions: true
);

Exception Handling

The package provides specific exceptions for different error scenarios:

use MohamedSaid\PaymobPayout\Exceptions\PaymobAuthenticationException;
use MohamedSaid\PaymobPayout\Exceptions\PaymobTransactionLimitException;
use MohamedSaid\PaymobPayout\Exceptions\PaymobInsufficientFundsException;
use MohamedSaid\PaymobPayout\Exceptions\PaymobInvalidAccountException;
use MohamedSaid\PaymobPayout\Exceptions\PaymobDuplicateTransactionException;
use MohamedSaid\PaymobPayout\Exceptions\PaymobRateLimitException;

try {
    $transaction = PaymobPayout::instantCashIn(
        issuer: IssuerType::VODAFONE,
        amount: 1000.00,
        msisdn: '01234567890'
    );
} catch (PaymobAuthenticationException $e) {
    // Handle authentication errors (403, invalid PIN, etc.)
    echo "Authentication failed: " . $e->getMessage();
    echo "Status code: " . $e->getStatusCode();
} catch (PaymobTransactionLimitException $e) {
    // Handle limit exceeded errors (583, 604, 6061, 6065)
    echo "Transaction limit exceeded: " . $e->getMessage();
} catch (PaymobInsufficientFundsException $e) {
    // Handle insufficient funds (6005)
    echo "Insufficient funds: " . $e->getMessage();
} catch (PaymobInvalidAccountException $e) {
    // Handle invalid account errors (618, 4055, etc.)
    echo "Invalid account: " . $e->getMessage();
} catch (PaymobDuplicateTransactionException $e) {
    // Handle duplicate transaction (501)
    echo "Duplicate transaction: " . $e->getMessage();
} catch (PaymobRateLimitException $e) {
    // Handle rate limiting (429)
    echo "Rate limit exceeded: " . $e->getMessage();
}

Dependency Injection

You can also use dependency injection instead of the facade:

use MohamedSaid\PaymobPayout\PaymobPayout;
use MohamedSaid\PaymobPayout\Enums\IssuerType;

class PaymentService
{
    public function __construct(
        private PaymobPayout $paymobPayout
    ) {}

    public function processWalletPayment(float $amount, string $phone): void
    {
        $transaction = $this->paymobPayout->walletCashIn(
            issuer: IssuerType::VODAFONE,
            amount: $amount,
            msisdn: $phone
        );
        
        // Handle the transaction result...
    }

    public function processAmanPayment(float $amount, string $phone, string $firstName, string $lastName, string $email): void
    {
        $transaction = $this->paymobPayout->amanCashIn(
            amount: $amount,
            msisdn: $phone,
            firstName: $firstName,
            lastName: $lastName,
            email: $email
        );
        
        // Handle the transaction result...
    }
}

Enum Helper Methods

All enums include helpful methods for retrieving human-readable names and filtering options:

Get Human-Readable Names

use MohamedSaid\PaymobPayout\Enums\IssuerType;
use MohamedSaid\PaymobPayout\Enums\BankCode;
use MohamedSaid\PaymobPayout\Enums\BankTransactionType;

// Get display names
echo IssuerType::VODAFONE->getLabel(); // "Vodafone Cash"
echo BankCode::CIB->getLabel(); // "Commercial International Bank"
echo BankTransactionType::SALARY->getLabel(); // "Salary"

Get All Options (with optional exclusions)

// Get all issuers
$allIssuers = IssuerType::all();

// Get all issuers except bank-related ones
$walletIssuers = IssuerType::all([
    IssuerType::BANK_WALLET,
    IssuerType::BANK_CARD
]);

// Get all bank codes except specific ones
$availableBanks = BankCode::all([
    BankCode::HSBC,
    BankCode::SCB
]);

// Get all transaction types except salary
$transactionTypes = BankTransactionType::all([
    BankTransactionType::SALARY
]);

Supported Features

Issuers

• Vodafone Cash - Instant wallet transactions
• Etisalat Cash - Instant wallet transactions
• Orange Cash - Instant wallet transactions
• Aman - Cash pickup service with reference numbers
• Bank Wallet - Bank wallet transactions
• Bank Card - Direct bank card disbursements (2 working days)

Bank Transaction Types

• SALARY - For concurrent or repeated payments
• CREDIT_CARD - For credit card payments
• PREPAID_CARD - For prepaid cards and Meeza cards payments
• CASH_TRANSFER - For bank accounts, debit cards etc.

Supported Bank Codes

• CIB - Commercial International Bank
• NBE - National Bank of Egypt
• MISR - Banque Misr
• ALEX - Bank of Alexandria
• QNB - QNB ALAHLI
• HSBC - HSBC Bank Egypt
• And 25+ other banks (see BankCode enum for complete list)

API Rate Limits

• Transaction Inquiry: 5 requests per minute (POST request)
• Budget Inquiry: 5 requests per minute (GET request)
• Bulk Transaction Inquiry: 50 transactions per request (POST request)

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mohamed Said
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Support

This package is provided as-is for community benefit. For official support, please contact Paymob directly.

For package-specific issues, please open an issue on GitHub.