README

Un package PHP complète et modulaire pour intégrer facilement tous les principaux systèmes de paiement en un clic !

🌟 Caractéristiques Principales

✅ Installation "Un Clic" - Installer et configurer plusieurs gateways en minutes
✅ Interface Unifiée - Une seule API pour Stripe, PayPal, Square, Wise, Coinbase, etc.
✅ Webhooks Automatiques - Gestion centralisée de tous les webhooks
✅ Dashboard Complet - Interface d'administration pour gérer les paiements
✅ Haute Sécurité - Chiffrement, validation, audit trail
✅ Tests Unitaires - 100% de couverture de tests
✅ Documentation Complète - Guides complets pour chaque gateway
✅ Support Multi-framework - Laravel, Symfony, Slim, Plain PHP

🚀 Démarrage Rapide

1️⃣ Installation

Option A: Via Packagist (Une fois publié)

composer require dontka/all-php-payment-gateway-manager

Option B: Via Chemin Local (Développement)

Si vous testez localement, ajouter à votre composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "../all-php-payment-gateway-manager",
            "options": {
                "symlink": true
            }
        }
    ],
    "require": {
        "dontka/all-php-payment-gateway-manager": "@dev"
    }
}

Puis:

composer update

2️⃣ Configuration selon votre Framework

🔷 Laravel (Recommandé)

Étape 1 : Enregistrer le Service Provider (généralement automatique)

// config/app.php
'providers' => [
    // ...
    PaymentGateway\ServiceProvider::class,
],

'aliases' => [
    // ...
    'Payment' => PaymentGateway\Facades\Payment::class,
],

Étape 2 : Publier les fichiers de configuration

php artisan vendor:publish --provider="PaymentGateway\ServiceProvider"

Étape 3 : Exécuter les migrations

php artisan migrate

Étape 4 : Configurer les variables d'environnement

# Copier le fichier d'exemple
cp .env.example .env

# Ajouter vos clés API
PAYPAL_CLIENT_ID=your_sandbox_client_id
PAYPAL_CLIENT_SECRET=your_sandbox_secret

STRIPE_API_KEY=sk_test_...
STRIPE_SECRET_KEY=sk_test_...

🔹 Symfony (Support PSR-4)

Étape 1 : Installer le package

composer require symfony/http-client
composer require dontka/all-php-payment-gateway-manager

Étape 2 : Créer un service dans config/services.yaml

services:
  payment.manager:
    class: PaymentGateway\Core\PaymentManager
    arguments:
      - '%env(PAYPAL_CLIENT_ID)%'
      - '%env(PAYPAL_CLIENT_SECRET)%'
      - '%env(STRIPE_API_KEY)%'

Étape 3 : Utiliser dans votre contrôleur

namespace App\Controller;

use PaymentGateway\Core\PaymentManager;

class PaymentController extends AbstractController
{
    public function __construct(private PaymentManager $paymentManager) {}

    public function charge()
    {
        $result = $this->paymentManager->charge([
            'gateway' => 'paypal',
            'amount' => 99.99,
            'currency' => 'USD',
        ]);
    }
}

🔸 PHP Vanilla (Sans Framework)

Étape 1 : Charger l'autoloader

<?php
require_once 'vendor/autoload.php';

use PaymentGateway\Core\PaymentManager;
use PaymentGateway\Gateways\PayPalGateway;

Étape 2 : Initialiser le PaymentManager

$paymentManager = new PaymentManager();

// Enregistrer le gateway PayPal
$paypalGateway = new PayPalGateway(
    apiKey: getenv('PAYPAL_CLIENT_ID'),
    secret: getenv('PAYPAL_CLIENT_SECRET'),
    mode: 'sandbox' // ou 'live'
);

$paymentManager->registerGateway('paypal', $paypalGateway);

Étape 3 : Traiter un paiement

$result = $paymentManager->charge([
    'gateway' => 'paypal',
    'amount' => 99.99,
    'currency' => 'USD',
    'customer' => ['email' => 'user@example.com'],
]);

if ($result['success']) {
    echo "✅ Paiement approuvé: " . $result['approval_link'];
} else {
    echo "❌ Erreur: " . $result['error'];
}

3️⃣ Premier Paiement (Tous les Frameworks)

Simple avec Laravel

use PaymentGateway\Facades\Payment;

// 1. Créer une commande PayPal
$order = Payment::gateway('paypal')->charge([
    'amount' => 99.99,
    'currency' => 'USD',
    'customer' => [
        'email' => 'client@example.com',
        'name' => 'Jean Dupont'
    ],
    'description' => 'Achat Premium - Produit XYZ'
]);

// 2. Rediriger le client vers PayPal
if ($order['success']) {
    return redirect($order['approval_link']);
}

// 3. Après approbation (Callback)
$captured = Payment::gateway('paypal')->captureOrderPayment($orderId);

if ($captured['success']) {
    echo "✅ Paiement réussi: " . $captured['capture_id'];
    // Sauvegarder en BDD, envoyer email, etc.
}

Simple avec Stripe

use PaymentGateway\Facades\Payment;

$result = Payment::gateway('stripe')->charge([
    'amount' => 99.99,
    'currency' => 'USD',
    'source' => 'tok_visa', // Token du client
    'description' => 'Achat Premium'
]);

if ($result['success']) {
    echo "✅ Paiement réussi: " . $result['transaction_id'];
} else {
    echo "❌ Erreur: " . $result['error'];
}

4️⃣ Intégration avec une Base de Données

Laravel Model (Eloquent)

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use PaymentGateway\Traits\HasPayments;

class Order extends Model
{
    use HasPayments;

    protected $fillable = ['user_id', 'amount', 'currency', 'status'];

    public function processPayment()
    {
        return $this->payment([
            'amount' => $this->amount,
            'currency' => $this->currency,
            'customer' => ['email' => $this->user->email],
            'description' => "Commande #{$this->id}"
        ]);
    }
}

// Usage
$order = Order::create([
    'user_id' => auth()->id(),
    'amount' => 199.99,
    'currency' => 'EUR'
]);

$result = $order->processPayment();

Suivi des Paiements

// Vérifier le statut d'un paiement
$status = Payment::gateway('paypal')->verify($transactionId);

if ($status['status'] === 'COMPLETED') {
    $order->update(['status' => 'paid']);
    $order->sendConfirmationEmail();
}

5️⃣ Webhooks et Notifications Automatiques

Configurer un webhook PayPal

Dans routes/api.php (Laravel)

Route::post('/webhooks/paypal', [\App\Http\Controllers\WebhookController::class, 'handlePayPal']);

Handler du webhook

namespace App\Http\Controllers;

use PaymentGateway\Facades\Payment;

class WebhookController extends Controller
{
    public function handlePayPal(Request $request)
    {
        $payload = $request->all();
        
        // Traiter le webhook
        $result = Payment::gateway('paypal')->handleWebhook(
            $payload,
            $request->headers->all()
        );
        
        if ($result['success']) {
            // Paiement complété/échoué
            $order = Order::where('transaction_id', $result['transaction_id'])
                ->update(['status' => $result['status']]);
            
            return response()->json(['status' => 'ok']);
        }
        
        return response()->json(['status' => 'error'], 400);
    }
}

Écouter les événements

use PaymentGateway\Events\PaymentSuccessEvent;
use PaymentGateway\Events\PaymentFailedEvent;

// Dans un service provider ou contrôleur
Payment::on(PaymentSuccessEvent::class, function($event) {
    // Envoyer email de confirmation
    Mail::send('emails.payment-confirmed', $event->toArray());
    
    // Logger l'événement
    Log::info('Payment successful', $event->toArray());
});

Payment::on(PaymentFailedEvent::class, function($event) {
    // Notifier l'utilisateur
    Notification::send($event->user, new PaymentFailedNotification());
});

6️⃣ Gestion des Erreurs

use PaymentGateway\Exceptions\PaymentException;
use PaymentGateway\Exceptions\ValidationException;

try {
    $result = Payment::charge([
        'amount' => 99.99,
        'currency' => 'INVALID', // ❌ Devise invalide
    ]);
} catch (ValidationException $e) {
    echo "❌ Validation échouée: " . $e->getField();
} catch (PaymentException $e) {
    echo "❌ Erreur de paiement: " . $e->getMessage();
}

7️⃣ Remboursements

// Remboursement complet
$refund = Payment::gateway('stripe')->refund($transactionId);

// Remboursement partiel
$refund = Payment::gateway('stripe')->refund(
    $transactionId,
    50.00, // Montant à rembourser
    ['reason' => 'Demande client']
);

if ($refund['success']) {
    echo "✅ Remboursement traité: " . $refund['refund_id'];
}

📦 Systèmes de Paiement Supportés

Phase 1 (Core)

• 🟢 Stripe - Cartes bancaires & ACH
• 🟢 PayPal - Paiement universel
• 🟢 Square - POS & E-commerce

Phase 2 (Extensions)

• 🟡 Wise - Virements internationaux
• 🟡 Coinbase Commerce - Crypto-monnaies
• 🟡 Apple Pay & Google Pay

Phase 3 (Avancé)

• 🟢 2Checkout, HyperPay, Flutterwave, Paystack...

📚 Documentation

💻 Exemples d'Utilisation Avancés

📌 Cas 1 : E-Commerce (Paiement Direct)

// 1. Créer une commande
$order = Order::create([
    'user_id' => auth()->id(),
    'items' => $cartItems,
    'total' => 199.99,
    'currency' => 'EUR',
    'status' => 'pending'
]);

// 2. Traiter le paiement Stripe
$payment = Payment::gateway('stripe')->charge([
    'amount' => 199.99,
    'currency' => 'EUR',
    'source' => $request->get('stripe_token'),
    'description' => "Commande #{$order->id}",
    'metadata' => ['order_id' => $order->id]
]);

// 3. Mettre à jour le statut
if ($payment['success']) {
    $order->update([
        'status' => 'paid',
        'transaction_id' => $payment['transaction_id'],
        'paid_at' => now()
    ]);
    
    // Envoyer email de confirmation
    Mail::send('emails.order-confirmed', ['order' => $order]);
    
    return redirect()->route('orders.show', $order)->with('success', '✅ Paiement réussi!');
} else {
    return back()->with('error', '❌ ' . $payment['error']);
}

📌 Cas 2 : Panier Différé (PayPal)

// 1. Créer une commande non-payée
$order = Order::create([
    'user_id' => auth()->id(),
    'status' => 'pending_payment',
    'total' => 299.99
]);

// 2. Créer l'ordre PayPal
$paypalOrder = Payment::gateway('paypal')->charge([
    'amount' => 299.99,
    'currency' => 'EUR',
    'customer' => [
        'email' => auth()->user()->email,
        'name' => auth()->user()->name
    ],
    'description' => "Commande #{$order->id}"
]);

if ($paypalOrder['success']) {
    // Sauvegarder l'order_id PayPal
    $order->update(['paypal_order_id' => $paypalOrder['order_id']]);
    
    // Rediriger vers PayPal
    return redirect($paypalOrder['approval_link']);
}

// 3. Après approbation (callback)
$captured = Payment::gateway('paypal')->captureOrderPayment(
    $request->get('orderId')
);

if ($captured['success']) {
    $order->update([
        'status' => 'paid',
        'paypal_capture_id' => $captured['capture_id'],
        'paid_at' => now()
    ]);
    
    return redirect()->route('orders.success', $order);
}

📌 Cas 3 : Abonnement avec Renouvellement

// 1. Créer un abonnement
$subscription = Subscription::create([
    'user_id' => auth()->id(),
    'plan' => 'premium',
    'price' => 9.99,
    'currency' => 'USD',
    'billings_cycle' => 'monthly',
    'status' => 'pending'
]);

// 2. Premier paiement
$payment = Payment::gateway('stripe')->charge([
    'amount' => 9.99,
    'currency' => 'USD',
    'source' => $request->get('token'),
    'description' => "Abonnement Premium - Mois 1",
    'metadata' => [
        'subscription_id' => $subscription->id,
        'billing_cycle' => 1
    ]
]);

if ($payment['success']) {
    $subscription->update([
        'status' => 'active',
        'stripe_subscription_id' => $payment['subscription_id'],
        'current_period_start' => now(),
        'current_period_end' => now()->addMonth()
    ]);
}

// 3. Renouvellement automatique via Webhook
// Le webhook PayPal/Stripe mettra automatiquement à jour

📌 Cas 4 : Gestion des Webhooks

// routes/api.php
Route::post('/webhooks/payment', [PaymentWebhookController::class, 'handle']);

// App/Http/Controllers/PaymentWebhookController.php
class PaymentWebhookController extends Controller
{
    public function handle(Request $request)
    {
        $gateway = $request->get('gateway'); // paypal, stripe, etc.
        
        // Traiter le webhook
        $result = Payment::gateway($gateway)->handleWebhook(
            $request->all(),
            $request->headers->all()
        );
        
        if (!$result['success']) {
            return response()->json(['error' => 'Invalid webhook'], 400);
        }
        
        // Mettre à jour le paiement
        $order = Order::where('transaction_id', $result['transaction_id'])->first();
        
        if (!$order) {
            return response()->json(['error' => 'Order not found'], 404);
        }
        
        // Synchroniser le statut
        $order->update(['status' => $result['status']]);
        
        // Déclencher les actions
        match($result['status']) {
            'completed' => $this->handlePaymentCompleted($order),
            'failed' => $this->handlePaymentFailed($order),
            'refunded' => $this->handlePaymentRefunded($order),
            default => null
        };
        
        return response()->json(['status' => 'ok']);
    }
    
    private function handlePaymentCompleted(Order $order)
    {
        // Activer la commande
        $order->activate();
        
        // Envoyer email
        Mail::send('emails.payment-confirmed', ['order' => $order]);
        
        // Déclencher événement personnalisé
        event(new OrderPaid($order));
    }
}

📌 Cas 5 : Remboursement Client

// 1. Initier un remboursement
public function refundOrder(Order $order, Request $request)
{
    // Valider que le paiement peut être remboursé
    if ($order->status !== 'paid') {
        return back()->with('error', 'Seuls les paiements complétés peuvent être remboursés');
    }
    
    // Montant du remboursement (optionnel)
    $amount = $request->get('amount', $order->total);
    
    // Traiter le remboursement
    $refund = Payment::gateway($order->gateway)->refund(
        $order->transaction_id,
        $amount,
        ['reason' => $request->get('reason')]
    );
    
    if ($refund['success']) {
        $order->update([
            'status' => 'refunded',
            'refund_id' => $refund['refund_id'],
            'refunded_at' => now(),
            'refund_amount' => $amount
        ]);
        
        // Notifier le client
        Mail::send('emails.refund-processed', ['order' => $order]);
        
        return back()->with('success', '✅ Remboursement traité');
    } else {
        return back()->with('error', '❌ ' . $refund['error']);
    }
}

// 2. Vérifier le statut du remboursement
$status = Payment::gateway($order->gateway)->verify($order->transaction_id);

if ($status['status'] === 'refunded') {
    echo "✅ Remboursement complété";
    echo "Montant: " . $status['refund_amount'];
}

📌 Cas 6 : Support Multi-Devise

// Accepter les paiements en plusieurs devises
$order = Order::create([
    'amount' => 100,
    'currency' => $request->get('currency') // EUR, USD, GBP, etc.
]);

// PayPal supporte 20+ devises
$payment = Payment::gateway('paypal')->charge([
    'amount' => 100,
    'currency' => 'EUR', // ✅ Non USD!
    'customer' => ['email' => 'user@example.com']
]);

// Taux de change automatique appliqué

📌 Cas 7 : Logs et Audit

// Tous les paiements sont automatiquement loggés
use PaymentGateway\Models\WebhookLog;
use PaymentGateway\Models\Transaction;

// Voir tous les paiements
$transactions = Transaction::where('gateway', 'paypal')
    ->where('status', 'completed')
    ->get();

// Voir tous les webhooks reçus
$webhooks = WebhookLog::where('gateway', 'paypal')
    ->where('status', 'received')
    ->latest()
    ->paginate(20);

// Voir les erreurs
$failed = Transaction::where('status', 'failed')
    ->whereDate('created_at', today())
    ->get();

// Logger personnalisé
Log::info('Payment processed', [
    'order_id' => $order->id,
    'transaction_id' => $payment['transaction_id'],
    'amount' => $payment['amount'],
    'gateway' => 'paypal'
]);

📌 Cas 8 : Événements Personnalisés

use PaymentGateway\Events\PaymentSuccessEvent;
use PaymentGateway\Events\PaymentFailedEvent;
use PaymentGateway\Events\WebhookReceivedEvent;

// Dans un service provider
Payment::on(PaymentSuccessEvent::class, function($event) {
    // Envoyer email
    Mail::send('emails.payment-success', ['event' => $event]);
    
    // Mettre à jour les stats
    Stats::increment('payments_completed', $event->amount);
    
    // Déclencher action
    $event->order->activate();
});

Payment::on(PaymentFailedEvent::class, function($event) {
    // Notifier l'admin
    Notification::send(Admin::all(), new PaymentFailedNotification($event));
    
    // Logger l'erreur
    Log::error('Payment failed', $event->toArray());
});

Payment::on(WebhookReceivedEvent::class, function($event) {
    // Audit trail
    AuditLog::create([
        'event' => 'webhook_received',
        'gateway' => $event->gateway,
        'type' => $event->event_type,
        'ip' => request()->ip()
    ]);
});

🔧 Configuration

Fichier .env

APP_NAME="My Store"
APP_ENV=production

# Stripe
STRIPE_API_KEY=sk_live_...
STRIPE_SECRET_KEY=sk_live_...

# PayPal
PAYPAL_MODE=live
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...

# Square
SQUARE_ACCESS_TOKEN=...

# General
PAYMENT_LOG_CHANNEL=single
PAYMENT_WEBHOOK_SECRET=...

Fichier config/payment.php

return [
    'default_gateway' => 'stripe',
    
    'gateways' => [
        'stripe' => [
            'driver' => 'stripe',
            'api_key' => env('STRIPE_API_KEY'),
            'secret_key' => env('STRIPE_SECRET_KEY'),
            'test_mode' => env('APP_ENV') !== 'production'
        ],
        
        'paypal' => [
            'driver' => 'paypal',
            'mode' => env('PAYPAL_MODE', 'sandbox'),
            'client_id' => env('PAYPAL_CLIENT_ID'),
            'client_secret' => env('PAYPAL_CLIENT_SECRET')
        ],
        
        'square' => [
            'driver' => 'square',
            'access_token' => env('SQUARE_ACCESS_TOKEN')
        ]
    ],
    
    'webhook_url' => env('APP_URL') . '/webhooks/payment',
    'webhook_secret' => env('PAYMENT_WEBHOOK_SECRET'),
    'log_channel' => env('PAYMENT_LOG_CHANNEL', 'single')
];

🎛️ Dashboard d'Administration

Accédez au dashboard à /admin/payments

Fonctionnalités :

• 📊 Statistiques en temps réel
• 📋 Liste complète des transactions
• ⚙️ Gestion des clés API
• 📝 Logs détaillés des webhooks
• 🔍 Recherche et filtrage avancés
• 💾 Export CSV/PDF
• 🔐 Paramètres de sécurité

🧪 Tests

Exécuter les tests :

# Tests unitaires
php ./vendor/bin/phpunit

# Tests spécifiques à Stripe
php ./vendor/bin/phpunit tests/Integration/StripeTest.php

# Avec couverture
php ./vendor/bin/phpunit --coverage-html coverage/

Créer un paiement de test :

php artisan payment:test --gateway=stripe --amount=10 --currency=USD

🔒 Sécurité

Points Importants

✅ Chiffrement - Toutes les clés API sont chiffrées
✅ Validation - Validation complète des entrées
✅ Webhooks - Vérification de signature sur tous les webhooks
✅ Logs - Audit trail complet de toutes les transactions
✅ CSRF - Protection CSRF sur tous les formulaires
✅ Rate Limiting - Protection contre les attaques par force brute

Bonnes Pratiques

// ✅ BON
Payment::charge([
    'amount' => $amount,
    'currency' => 'USD',
    'source' => $token  // Token Stripe/PayPal
]);

// ❌ MAUVAIS - Ne jamais envoyer les numéros de carte
$payment = Payment::charge([
    'amount' => $amount,
    'card_number' => '4242' // ❌ DANGER!
]);

Consultez le Guide de Sécurité pour plus de détails.

📈 Performances

Benchmarks (sur 1000 paiements)

🤝 Contribution

Les contributions sont les bienvenues !

1. Fork le repo
2. Créer une branche (git checkout -b feature/AmazingFeature)
3. Commit les changements (git commit -m 'Add AmazingFeature')
4. Push vers la branche (git push origin feature/AmazingFeature)
5. Ouvrir une Pull Request

Code Style

# Formater le code
php ./vendor/bin/php-cs-fixer fix

# Analyser statiquement
php ./vendor/bin/phpstan analyse

📋 Roadmap

Q1 2024

• ✅ Stripe, PayPal, Square
• ✅ Dashboard basique
• ✅ Tests unitaires

Q2 2024

• 🔄 Wise, Coinbase
• 🔄 Dashboard avancé
• 🔄 Intégration Symfony

Q3 2024

• 📋 Apple Pay, Google Pay
• 📋 Support multi-devises avancé
• 📋 Analytics détaillée

Q4 2024

• 📋 2Checkout, HyperPay
• 📋 Mobile app
• 📋 API publique

🐛 Problèmes Connus

❓ FAQ

Q: Puis-je utiliser plusieurs gateways?
R: Oui! Chaque gateway fonctionne indépendamment.

Q: Comment gérer les remboursements?
R: Utilisez Payment::refund() avec le transaction ID.

Q: Les webhooks sont-ils sécurisés?
R: Oui, tous les webhooks sont vérifiés avec une signature.

Q: Pouvez-vous supporter [mon gateway]?
R: Oui! Consultez le guide de contribution.

📞 Support

• 📧 Email : support@example.com
• 💬 Discord : Rejoindre le serveur
• 🐛 Issues : GitHub Issues
• 📖 Q&A : GitHub Discussions

📄 License

Ce projet est sous license MIT. Voir LICENSE pour plus de détails.

🙏 Remerciements

Merci à tous les contributeurs et à la communauté PHP!

• 🌟 Stripe pour leur excellente API
• 🌟 PayPal pour leur flexibilité
• 🌟 Square pour leur innovation
• 🌟 La communauté Laravel & Symfony

📊 Statistiques

Créé avec ❤️ pour la communauté PHP

Dernière mise à jour : 10 Février 2026
Version : 1.0.0-beta
Mainteneur : @dontka