README

Un package Laravel robuste pour intégrer facilement le système de paiement et de séquestre (Escrow) de FedaPay au sein de vos applications. C'est la solution idéale pour les plateformes, marketplaces et services nécessitant une rétention sécurisée des fonds avant validation et livraison.

📋 Prérequis

Avant d'installer le package, assurez-vous que votre environnement respecte les exigences minimales suivantes :

PHP : 8.1 ou supérieur
Laravel : 10.0 ou supérieur
Base de données : Votre modèle User doit impérativement utiliser des UUID en tant que clé primaire (au lieu de l'auto-incrément classique).

🚀 Installation

Installez le package directement via Composer en utilisant la commande suivante :

composer require eunockweb/safepay

Une fois le package installé, publiez le fichier de configuration fourni par le package :

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

(Optionnel) Les migrations du package sont chargées automatiquement. Cependant, si vous souhaitez les visualiser ou les modifier directement dans votre dossier database/migrations, vous pouvez les publier avec cette commande :

php artisan vendor:publish --tag=safepay-migrations

Appliquez ensuite les migrations pour créer les tables nécessaires (transactions et transaction_logs) :

php artisan migrate

⚙️ Configuration

Pour que le package puisse communiquer avec l'API FedaPay, vous devez ajouter et configurer les variables suivantes dans votre fichier .env :

# Clé secrète de votre compte FedaPay
FEDAPAY_SECRET_KEY="sk_sandbox_xxxxxxxxxxxxxxxxx"

# Environnement FedaPay ('sandbox' pour l'environnement de test, 'live' en production)
FEDAPAY_ENVIRONMENT="sandbox"

# Clé secrète de votre Webhook (trouvable dans votre dashboard FedaPay)
FEDAPAY_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxx"

🛠️ Mise en place

Pour permettre à vos utilisateurs d'interagir nativement avec le système Escrow, ajoutez simplement le trait HasPayments à votre modèle User typique (app/Models/User.php) :

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Safepay\Traits\HasPayments;

class User extends Authenticatable
{
    use HasPayments; // <-- Ajouter cette ligne

    // ... reste de votre modèle
}

💻 Utilisation

Le trait HasPayments ainsi que le package vous offrent des raccourcis intuitifs pour la gestion des fonds. Voici un aperçu des méthodes principales :

1. Bloquer des fonds (Charge Escrow)

Permet d'initier une transaction où l'argent du client sera bloqué dans le système.

$user = auth()->user();
$prestataireId = 'uuid-du-prestataire';
$transactionId = 'fedapay_tx_123456'; // L'identifiant propre à FedaPay

$transaction = $user->chargeEscrow($transactionId, $prestataireId);

// Vous pouvez utiliser le résultat de la transaction pour la suite.

2. Libérer les fonds (Release Escrow)

Une fois la commande livrée ou le service validé, libérez les fonds pour que le prestataire les reçoive en effectuant un appel au service d'escrow :

use Safepay\Services\EscrowService;

public function validerCommande(EscrowService $escrowService, $transactionId)
{
    $result = $escrowService->release($transactionId);

    if ($result['success']) {
        return response()->json(['message' => 'Les fonds ont bien été libérés pour le prestataire.']);
    }

    return response()->json(['error' => $result['message']], 400);
}

Commission et délai : ESCROW_COMMISSION (en %, défaut 2.5) est retenue sur le versement au prestataire (montant versé = montant − commission, enregistrée dans transactions.commission). ESCROW_DELAY (en heures, défaut 48, 0 pour désactiver) planifie une libération automatique via ReleaseEscrowJob. Cela nécessite un driver de queue autre que sync et un worker actif ; avec sync, aucune libération automatique n'est planifiée.

3. Consulter l'historique (Escrow Transactions)

Récupérer facilement l'historique des transactions liées à la plateforme par l'utilisateur connecté en passant par la relation Eloquent :

$user = auth()->user();

// Liste des transactions
$transactions = $user->escrowTransactions()->latest()->get();

🪝 Webhook

Pour que la plateforme soit synchronisée avec l'état réel du paiement FedaPay de l'utilisateur, vous devez mettre en place un Webhook. Le package expose déjà une route prête à l'emploi.

L'endpoint à configurer est : POST https://votre-domaine.com/webhook/fedapay

Comment le configurer :

Connectez-vous à votre Dashboard FedaPay.
Allez dans Webhooks > Créer un Webhook.
Renseignez l'URL de destination : https://votre-domaine.com/webhook/fedapay.
Sélectionnez les événements pertinents (ex: transaction.approved, transaction.canceled).
Copiez la clé Signature (Secret Key) générée par FedaPay.
Collez-la dans votre .env à la variable FEDAPAY_WEBHOOK_SECRET.

Important :

La route est enregistrée dans le groupe api (pas de CSRF). Si FEDAPAY_WEBHOOK_SECRET est absent, le webhook répond 500 et rien n'est traité.
Le client et le prestataire ne sont jamais lus depuis la requête du webhook : renseignez-les à la création de la transaction FedaPay via custom_metadata (client_id et prestataire_id).
Le traitement passe par la queue (5 essais avec backoff) : lancez un worker (php artisan queue:work).

🧪 Tests

Si vous souhaitez contribuer ou simplement vérifier que le package fonctionne parfaitement avant déploiement, exécutez la commande PHPUnit intégrée :

./vendor/bin/phpunit

Tous les tests unitaires et fonctionnels du package seront lancés pour vérifier que le comportement du séquestre et la vérification des signatures du Webhook sont intègres.

🤝 Comment contribuer ?

Vous avez identifié un problème ou souhaitez apporter une amélioration ? Suivez ces quelques étapes :

Fork du dépôt.
Créez une nouvelle branche de fonctionnalité (git checkout -b feature/AjoutSuperFonctionnalite).
Commit de vos modifications (git commit -m 'Ajout de la super fonctionnalité').
Push sur votre la branche (git push origin feature/AjoutSuperFonctionnalite).
Ouvez une Pull Request.

Si vous rencontrez des bugs ou que vous avez des idées de nouvelles fonctionnalités, n'hésitez pas à ouvrir une Issue !

eunockweb / safepay

Package info

Security

Statistics