Laravel YabetooPay

Une intégration Laravel simple, robuste et générique pour la passerelle de paiement YabetooPay (Mobile Money).

Fonctionnalités

• Création d'intentions de paiement (Payment Intent).
• Confirmation d'intentions de paiement (avec déclenchement du push USSD MoMo).
• Récupération et vérification du statut d'un paiement.
• Middleware de vérification de signature HMAC-SHA256 pour sécuriser vos webhooks.
• Déclenchement d'un événement Laravel pour l'enregistrement et le suivi des journaux de requêtes (decoupled logging).

Installation

Option A : Depuis Packagist (une fois publié)

Installez le package via Composer :

composer require opennebel/laravel-yabetoopay

Option B : Utilisation en local (avant publication)

Si vous souhaitez utiliser ce package localement dans un autre projet sans le publier immédiatement sur Packagist, ajoutez ce qui suit au fichier composer.json de votre autre projet :

"repositories": [
    {
        "type": "path",
        "url": "../chemin/vers/yabetoo-laravel"
    }
],

Ensuite, exécutez la commande suivante dans votre autre projet :

composer require opennebel/laravel-yabetoopay:dev-main

Configuration

Publiez le fichier de configuration dans votre application Laravel :

php artisan vendor:publish --provider="Yabetoopay\Laravel\YabetooServiceProvider" --tag="yabetoo-config"

Cela va créer un fichier de configuration config/yabetoo.php. Vous pouvez configurer les variables dans votre fichier .env :

YABETOO_BASE_URL=https://pay.api.yabetoopay.com
YABETOO_SECRET_KEY=votre_cle_secrete_ici
YABETOO_WEBHOOK_SECRET=votre_secret_de_webhook_ici
YABETOO_VERIFY_SSL=true
YABETOO_COUNTRY=cg
YABETOO_CURRENCY=xaf

Utilisation

Le package enregistre automatiquement la Facade Yabetoo et résout le client singleton depuis le conteneur IoC.

1. Créer une intention de paiement (Payment Intent)

use Yabetoopay\Laravel\Facades\Yabetoo;
use Yabetoopay\Laravel\YabetooException;

try {
    $response = Yabetoo::createPaymentIntent(
        amount: 1000, // En centimes ou selon les spécifications de la devise
        currency: 'XAF',
        description: 'Achat de crédits SMS',
        metadata: ['payment_id' => 42],
        paymentId: 42 // Optionnel : identifiant local pour le traçage des logs
    );

    $intentId = $response['id'];
    $clientSecret = $response['clientSecret'];
    
    // Enregistrez ces informations sur votre paiement local
} catch (YabetooException $e) {
    // Gérer l'erreur
    $errorMessage = $e->getMessage();
    $errorData = $e->response; // Contenu brut de la réponse d'erreur de l'API
}

2. Confirmer un paiement (Déclencher le push USSD)

La confirmation déclenche la notification USSD sur le téléphone du client. Comme cet appel peut être long à répondre (attente réseau), il est fortement conseillé de l'exécuter dans un Job asynchrone (Queue).

use Yabetoopay\Laravel\Facades\Yabetoo;

$response = Yabetoo::confirmPaymentIntent(
    intentId: $intentId,
    clientSecret: $clientSecret,
    msisdn: '061234567',
    operator: 'mtn', // ex: mtn, airtel
    country: 'cg', // ex: cg
    paymentId: 42 // Optionnel
);

3. Récupérer le statut d'un paiement (Polling)

use Yabetoopay\Laravel\Facades\Yabetoo;

$response = Yabetoo::getPaymentIntent($intentId);

if ($response['status'] === 'succeeded') {
    // Le paiement est réussi !
}

Sécuriser vos Webhooks

YabetooPay envoie des événements à votre application par webhook. Pour sécuriser votre route et valider la signature de ces requêtes, utilisez le middleware inclus dans le package.

Enregistrement du Middleware

Laravel 11 / 12 / 13 (bootstrap/app.php) :

use Yabetoopay\Laravel\Http\Middleware\VerifyYabetooSignature;

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'yabetoo.signature' => VerifyYabetooSignature::class,
    ]);
})

Laravel 10 (app/Http/Kernel.php) :

protected $routeMiddleware = [
    'yabetoo.signature' => \Yabetoopay\Laravel\Http\Middleware\VerifyYabetooSignature::class,
];

Utilisation dans les routes :

Route::post('/webhooks/yabetoopay', [YabetooWebhookController::class, 'handle'])
    ->middleware('yabetoo.signature');

Journalisation (Logging)

Pour garder le package indépendant de la structure de votre base de données, le client déclenche l'événement Yabetoopay\Laravel\Events\YabetooRequestLogged après chaque requête HTTP.

Vous pouvez écouter cet événement dans votre application pour enregistrer les requêtes dans votre table de logs ou votre système de journalisation.

1. Créer un Listener

Générez un Listener dans votre projet hôte :

php artisan make:listener LogYabetooRequest --event="Yabetoopay\Laravel\Events\YabetooRequestLogged"

2. Implémenter la logique d'enregistrement

Dans app/Listeners/LogYabetooRequest.php :

<?php

namespace App\Listeners;

use Yabetoopay\Laravel\Events\YabetooRequestLogged;
use App\Models\PaymentLog; // Votre propre modèle de log

class LogYabetooRequest
{
    public function handle(YabetooRequestLogged $event): void
    {
        PaymentLog::create([
            'payment_id' => $event->paymentId,
            'direction' => $event->direction,
            'method' => $event->method,
            'url' => $event->url,
            'payload' => $event->payload,
            'response' => $event->response,
            'response_status' => $event->responseStatus,
        ]);
    }
}

Licence

Ce package est distribué sous licence MIT. Voir le fichier LICENSE.md pour plus d'informations.