README

Package Laravel pour l'intégration de la passerelle de paiement CMI (Centre Monétique Interbancaire) — la solution de paiement bancaire marocaine.

Fonctionnalités

• API fluide pour initier les paiements facilement
• Génération et vérification sécurisée du hash HMAC
• Support multi-boutiques (SaaS)
• Intégration des événements Laravel
• Journalisation des transactions en base de données
• Contrôleur de callback intégré
• Vue Blade de redirection avec auto-submit
• Commande Artisan de test
• Zéro dépendance externe

Prérequis

• PHP 8.1+
• Laravel 10, 11 ou 12

Installation

composer require alouspike/cmi-payment

Le package se découvre automatiquement. Pas besoin d'enregistrer manuellement le service provider.

Publier la configuration

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

Publier et exécuter les migrations

php artisan vendor:publish --tag=cmi-migrations
php artisan migrate

Publier les vues (optionnel)

php artisan vendor:publish --tag=cmi-views

Configuration

Ajoutez ces variables à votre fichier .env :

CMI_CLIENT_ID=votre_id_marchand
CMI_STORE_KEY=votre_cle_secrete
CMI_OK_URL=https://votresite.com/payment/success
CMI_FAIL_URL=https://votresite.com/payment/failed
CMI_SHOP_URL=https://votresite.com
CMI_CALLBACK_URL=https://votresite.com/cmi/callback
CMI_SANDBOX=true
CMI_HASH_ALGORITHM=SHA512
CMI_CURRENCY=504
CMI_LANG=fr
CMI_STORE_TRANSACTIONS=true

Options complètes

URL de production

Pour la production, modifiez :

CMI_BASE_URI=https://payment.cmi.co.ma/fim/est3Dgate
CMI_SANDBOX=false

Utilisation

Paiement simple

use Cmi;

// Dans votre contrôleur
public function pay()
{
    return Cmi::amount(150.00)
        ->orderId('CMD-001')
        ->email('client@email.com')
        ->pay();
}

Paiement avancé

use Cmi;
use Alouspike\CmiPayment\Enums\Currency;
use Alouspike\CmiPayment\Enums\Language;

return Cmi::amount(250.50)
    ->orderId('CMD-002')
    ->customerName('Ahmed Alami')
    ->email('ahmed@email.com')
    ->phone('0661000000')
    ->currency(Currency::MAD)
    ->lang(Language::FR)
    ->description('Achat en ligne #002')
    ->billingAddress('123 Rue Hassan II', 'Casablanca', 'MA')
    ->sessionTimeout(600)
    ->autoRedirect(true)
    ->okUrl('https://monsite.com/custom/success')
    ->failUrl('https://monsite.com/custom/fail')
    ->extraData(['champ_personnalise' => 'valeur'])
    ->pay();

Multi-Boutiques (SaaS)

return Cmi::useCredentials(
    clientId: $shop->cmi_client_id,
    storeKey: $shop->cmi_store_key,
)->amount(100.00)
  ->orderId('CMD-003')
  ->email('test@test.com')
  ->pay();

Gestion des callbacks

Automatique (Contrôleur intégré)

Le package enregistre automatiquement une route POST /cmi/callback qui gère la vérification du hash, la mise à jour des transactions et le dispatch des événements.

Utilisation du Trait

Dans votre contrôleur, utilisez le trait CmiGateway pour gérer les redirections OK/Fail :

use Alouspike\CmiPayment\Traits\CmiGateway;
use Alouspike\CmiPayment\CmiPaymentResponse;

class PaymentController extends Controller
{
    use CmiGateway;

    protected function onCmiPaymentSuccess(CmiPaymentResponse $response)
    {
        $orderId = $response->getOrderId();
        // Mettre à jour la commande, notifier l'utilisateur...
        return redirect()->route('orders.show', $orderId)
            ->with('success', 'Paiement effectué avec succès !');
    }

    protected function onCmiPaymentFailed(CmiPaymentResponse $response)
    {
        return redirect()->route('checkout')
            ->with('error', 'Le paiement a échoué. Veuillez réessayer.');
    }
}

Puis dans vos routes :

Route::post('/payment/success', [PaymentController::class, 'cmiOk']);
Route::post('/payment/failed', [PaymentController::class, 'cmiFail']);

Vérification manuelle du hash

use Cmi;

if (Cmi::verifyHash($request->all())) {
    // Le hash est valide
}

Événements

Le package dispatch les événements suivants :

Écouter les événements

// Dans EventServiceProvider ou avec Event::listen
use Alouspike\CmiPayment\Events\CmiPaymentSucceeded;
use Alouspike\CmiPayment\Events\CmiPaymentFailed;

Event::listen(CmiPaymentSucceeded::class, function ($event) {
    $response = $event->response;
    $orderId = $response->getOrderId();
    $amount = $response->getAmount();
    // Envoyer un email de confirmation, mettre à jour le statut...
});

Event::listen(CmiPaymentFailed::class, function ($event) {
    $response = $event->response;
    // Journaliser l'échec, notifier l'administrateur...
});

Méthodes de CmiPaymentResponse

Commande Artisan

php artisan cmi:test

Vérifie votre configuration CMI et affiche un exemple de code de paiement.

Cartes de test

Utilisez ces cartes en mode sandbox :

Note : Les numéros de cartes de test peuvent varier selon votre contrat CMI. Contactez le support CMI pour les identifiants de test exacts.

Dépannage

Erreurs "Hash invalide"

• Vérifiez que CMI_STORE_KEY correspond exactement à ce que CMI vous a fourni
• Assurez-vous que CMI_HASH_ALGORITHM correspond à votre configuration CMI (SHA512 ou SHA256)
• Vérifiez que votre URL de callback est accessible depuis internet (CMI envoie des requêtes serveur à serveur)

Callback non reçu

• L'URL de callback doit être accessible publiquement (pas localhost)
• Assurez-vous que votre pare-feu autorise les requêtes POST provenant des serveurs CMI
• Vérifiez que la route cmi/callback n'est pas bloquée par un middleware

Token CSRF invalide

Le package exclut automatiquement les routes CMI de la vérification CSRF. Si vous rencontrez toujours des problèmes, assurez-vous que les routes du package sont chargées correctement.

Transaction non sauvegardée

• Assurez-vous d'avoir exécuté php artisan migrate
• Vérifiez que CMI_STORE_TRANSACTIONS=true dans votre .env

Sécurité

• Toutes les données de callback sont vérifiées via le hash HMAC avant traitement
• La clé secrète n'est jamais exposée dans les formulaires ou le code côté client
• Les données de transaction sont validées côté serveur
• Le middleware VerifyCmiHash peut être appliqué à n'importe quelle route pour une sécurité supplémentaire
• La protection CSRF est maintenue sur toutes les routes non-CMI

Licence

Licence MIT. Voir LICENSE pour plus d'informations.