Download the PHP package andydefer/laravel-pawapay without Composer

Laravel PawaPay

Intégration Laravel du SDK PawaPay pour les paiements Mobile Money en Afrique.

Table des matières

1. Introduction
2. Installation
3. Configuration
4. Routes exposées
5. Utilisation
6. Contrats et extension
7. Hooks du service PawaPay
8. Gestion des erreurs
9. Traitement des callbacks entrants
10. Tests
11. Sécurité
12. Compatibilité

1. Introduction

Objectif

andydefer/laravel-pawapay expose les opérations PawaPay (dépôts Mobile Money, statuts, webhooks, pages de paiement) sous forme d'endpoints HTTP Laravel prêts à l'emploi.

Le package s'appuie sur andydefer/php-pawapay, qui contient toute la logique métier et les objets typés (Record, Data, ErrorResponseData). Laravel PawaPay n'ajoute que la couche transport : routes, validation, injection.

Ce que le package fournit

• 5 endpoints HTTP : initier un dépôt, vérifier un dépôt, renvoyer un webhook, créer une page de paiement, recevoir un callback PawaPay.
• 4 FormRequest : validation stricte, application des whitelists et construction de Record typés. Chaque Record expose un data bag optionnel pour porter les champs non réservés.
• 5 Action : résolvent le service PawaPay via la configuration, appellent l'opération correspondante et renvoient une Data typée. Si le service retourne une ErrorResponseData, l'action propage le code HTTP porté par cette erreur.
• Une configuration unique : token, URL, service_fqcn, handle_callback_fqcn, devises, langues, pays, providers et types de payeur autorisés.
• Deux points d'extension : remplacer le service PawaPay (service_fqcn) ou le handler de callbacks (handle_callback_fqcn) sans modifier le package.
• Des hooks applicatifs : le service php-pawapay expose des points d'extension before* / after* sur les quatre opérations. Voir section 7.

Ce que le package ne fait pas

• Aucune authentification. Les routes sont publiées sans middleware.
• Aucune persistance. Le package ne touche pas à la base de données.
• Aucune vérification de signature de callback. Le handler applicatif en est responsable.

2. Installation

Le PawapayServiceProvider est découvert automatiquement par Laravel.

3. Configuration

3.1 Publier les fichiers

• Config publiée dans config/pawapay.php.
• Routes publiées dans routes/laravel-pawapay.php.

3.2 Charger les routes

Les routes ne sont pas chargées automatiquement. Charge-les explicitement depuis ton application :

Tu contrôles ainsi le préfixe, les middlewares et l'ordre de chargement.

3.3 Fichier de configuration

3.4 Clés de configuration

3.5 Variables d'environnement

3.6 Restreindre les valeurs autorisées

Toute valeur absente de ces listes est rejetée par les FormRequest avec un 422.

3.7 Cas concret : configuration Afya (RDC)

4. Routes exposées

Le fichier routes/laravel-pawapay.php déclare cinq endpoints, tous en POST, sous le préfixe pawapay.

Note sur la route callback

La route callback utilise EmptyRequest (du package laravel-actions) et non un FormRequest dédié. Pawapay n'est pas un client à valider : le payload est vérifié par le handler applicatif (handle_callback_fqcn), pas par les règles Laravel.

Ne protège pas la route callback avec auth:sanctum. C'est Pawapay qui l'appelle en externe. La sécurité repose sur la vérification de signature dans le handler.

5. Utilisation

5.1 Initier un dépôt

Requête :

Paramètres :

Les champs non listés dans rules() mais présents dans la requête sont collectés dans le data bag du Record (voir section 6.4).

Réponse succès (200) :

Statuts : ACCEPTED, REJECTED, DUPLICATE_IGNORED.

5.2 Vérifier un dépôt

Réponse succès (200) :

Statuts de recherche : FOUND, NOT_FOUND, REJECTED.

Statuts de dépôt : ACCEPTED, PROCESSING, IN_RECONCILIATION, COMPLETED, FAILED, REJECTED.

5.3 Renvoyer un webhook

Réponse succès (200) :

Statuts : ACCEPTED, REJECTED.

5.4 Créer une page de paiement

Paramètres :

Réponse succès (200) :

Redirige l'utilisateur vers redirectUrl pour qu'il effectue le paiement.

6. Contrats et extension

6.1 PawapayConfigInterface

Contrat de la configuration. Utilisé par les Action pour résoudre le service et le handler, et par les FormRequest pour valider les valeurs autorisées.

6.2 PawapayInterface

Contrat du service PawaPay. Les Action ne connaissent que cette interface.

6.3 HandlesCallbacksInterface

Contrat du handler de callbacks entrants. Quatre méthodes, une par type d'opération.

6.4 Remplacer le service PawaPay

Option A — Modifier service_fqcn.

Contraintes :

• La classe doit étendre PawapayService ou implémenter PawapayInterface.
• Son constructeur doit être auto-résolvable par le conteneur Laravel.

Option B — Binder l'interface.

L'option B n'a d'effet que si service_fqcn reste égal à PawapayService::class.

6.5 Remplacer le handler de callbacks

Option A — Modifier handle_callback_fqcn.

La classe doit implémenter HandlesCallbacksInterface et avoir un constructeur auto-résolvable.

Option B — Étendre HandlesCallback.

Le package fournit un stub vide AndyDefer\LaravelPawapay\Callbacks\HandlesCallback. Étends-le pour ne surcharger que les méthodes utiles.

6.6 Le data bag des Record

Chaque FormRequest construit un Record avec un data bag optionnel. Ce bag contient tous les champs présents dans la requête mais non listés dans rules(). Il permet à l'application hôte d'attacher des informations contextuelles (identifiant interne, marqueur, note) sans étendre le Record du SDK.

order_id et customer_segment ne sont pas dans rules(). Ils aboutissent dans $record->data, un StrictAssociative accessible depuis les hooks du service ou depuis toute couche applicative qui consomme le Record.

7. Hooks du service PawaPay

Le service andydefer/php-pawapay expose dix hooks protected — deux par opération + deux pour les callbacks — que l'application hôte peut surcharger pour greffer sa logique métier sans réécrire le comportement PawaPay.

Les hooks sont appelés dans cet ordre, à chaque invocation de l'opération :

7.1 Liste des hooks

7.2 Créer un service applicatif

Puis déclare-le dans la config :

Les Action du package résolvent automatiquement cette classe via le conteneur.

7.3 Accéder au data bag depuis un hook

7.4 Ce qu'il ne faut pas faire dans un hook

• Émettre un appel HTTP vers PawaPay : ce n'est pas le rôle du hook, et cela provoquerait un double appel.
• Lever une exception pour « annuler » l'opération : préférer le retour d'un ErrorResponseData pour un court-circuit contrôlé. Les exceptions doivent rester réservées aux cas réellement exceptionnels.
• Modifier la Data : elle est readonly. Un hook after* observe le résultat, il ne le transforme pas.

8. Gestion des erreurs

Le package distingue trois niveaux.

8.1 Validation (HTTP 422)

Les FormRequest rejettent les payloads invalides avant toute exécution.

8.2 Refus PawaPay

Deux cas, distingués par le type de retour du service.

Cas A — Data avec failureReason non-null (HTTP 200).

Cas B — ErrorResponseData (HTTP non-200).

L'action propage le code HTTP embarqué.

Codes d'erreur possibles :

8.3 Erreurs techniques

Levées par le conteneur ou le service si :

• service_fqcn n'est pas résolvable (BindingResolutionException) ;
• handle_callback_fqcn n'est pas résolvable (BindingResolutionException) ;
• l'implémentation n'implémente pas le contrat attendu (TypeError) ;
• une erreur réseau se produit dans le SDK sous-jacent.

9. Traitement des callbacks entrants

Pawapay envoie les callbacks (deposit, payout, refund, checkout) sur l'endpoint unique POST /pawapay/callback. Le SDK détecte l'opération à partir des champs présents dans le payload et dispatche vers la méthode correspondante du handler.

9.1 Comportement du package

CallbackAction :

1. Lit le payload brut depuis la Request injectée.
2. Détecte l'opération via CallbackOperationType::fromPayload().
3. Hydrate le Struct correspondant.
4. Résout le service via service_fqcn et le handler via handle_callback_fqcn.
5. Appelle $service->handleCallback($struct, $handler).
6. Retourne 204 No Content.

9.2 Champs discriminants

checkoutId est vérifié en premier car un checkout contient aussi un objet deposit imbriqué.

9.3 Écrire un handler

Puis déclare-le :

9.4 Sécurité des callbacks

Le package ne fait pas :

• la vérification de signature (HMAC, JWT, signature HTTP) ;
• la déduplication (idempotence) ;
• la whitelist d'IP source.

Ces trois responsabilités doivent être implémentées dans le handler (handle_callback_fqcn) avant de traiter le callback. Une exception levée dans le handler se traduit par un 500, ce qui indique à Pawapay de réessayer.

9.5 Idempotence recommandée

Utilise une table processed_callbacks avec une contrainte unique sur l'identifiant du callback (depositId, payoutId, refundId ou checkoutId) :

10. Tests

Le package fournit un IntegrationTestCase basé sur orchestra/testbench. Chaque test enregistre le vrai endpoint via action_route(...) et remplace le client HTTP bas niveau par un MockPawapayClient.

Pour injecter une configuration alternative, utilise une classe de test dédiée :

Puis dans un test :

11. Sécurité

• Routes non protégées par défaut. Ajoute tes middlewares (auth:sanctum, throttle:60,1, signature HMAC…) dans le fichier publié.
• Route callback non protégée par auth. Pawapay l'appelle en externe. La sécurité repose sur la vérification de signature dans le handler.
• PAWAPAY_API_TOKEN côté serveur uniquement. Ne jamais l'exposer au frontend.
• Restriction des valeurs via la config : devises, langues, pays, providers, types de payeur.
• customer_message limité à 22 caractères conformément à PawaPay.
• metadata limité à 10 clés.
• client_reference_id limité à 64 caractères, alphanumérique avec tirets.
• phone_number au format E.164 sans + validé par FormRequest.
• data bag : les champs non réservés sont conservés dans un StrictAssociative typé, pas dans un tableau brut non contrôlé.
• Idempotence des callbacks à la charge du handler applicatif.
• Vérification de signature des callbacks à la charge du handler applicatif.

12. Compatibilité

Licence

MIT © Andy Defer