​
Webhooks PawaPay

Locayo utilise PawaPay comme passerelle de paiement mobile money. Lorsqu’un paiement est effectue (depot, remboursement ou commission), PawaPay envoie un callback HTTP (webhook) a Locayo pour confirmer le statut de la transaction.
Les webhooks sont traites de maniere asynchrone via Celery. Le endpoint repond immediatement a PawaPay avec {"status": "received"} puis delegue le traitement en arriere-plan. Cela garantit que Locayo repond en moins de 200ms, meme en cas de charge elevee.

​
Architecture du flux webhook

​
Flux de confirmation de depot (loyer)

Lorsqu’un locataire paie son loyer via mobile money, le flux suivant se deroule :
1

Le locataire initie le paiement

Depuis le portail locataire ou a la demande du bailleur, le locataire saisit son numero de telephone et son operateur (MTN, Orange, Wave).
2

PawaPay envoie un USSD Push

PawaPay envoie une requete USSD au telephone du locataire. Celui-ci valide avec son code PIN.
3

PawaPay envoie le callback

Une fois la transaction confirmee, PawaPay envoie un callback HTTP a l’endpoint /api/v1/payments/webhooks/pawapay avec le statut COMPLETED.
4

Locayo verifie la signature

Le callback est authentifie via la signature RFC-9421 incluse dans les en-tetes HTTP. Si la signature est invalide, le webhook est rejete avec un statut 403.
5

Traitement asynchrone

Le paiement est traite en arriere-plan par Celery : enregistrement en base, generation du recu PDF, mise a jour de l’echeancier et envoi des notifications.

​
Flux de remboursement (caution)

Le remboursement de la caution utilise le systeme de payout PawaPay : Les payouts sont utilises dans deux cas :
Cas d’usageDescription
Remboursement de cautionLa caution est renvoyee au locataire a la resiliation du bail
Liberation d’escrowLes fonds reserves pour un service marketplace sont liberes vers le prestataire (87,5%) apres validation du travail
Les payouts envoient l’argent directement sur le compte mobile money du destinataire. Une fois le payout initie, il ne peut pas etre annule. Verifiez toujours le numero de telephone du destinataire avant de declencher un remboursement.

​
Detection des paiements de commission

Lorsqu’un webhook est recu, Locayo identifie automatiquement le type de paiement :
1

Verification escrow marketplace

Le systeme verifie d’abord si le depositId correspond a un depot d’escrow marketplace (cle Redis pawapay_escrow:{depositId}). Si oui, le statut du job passe a ESCROW_FUNDED et le prestataire est notifie.
2

Verification commission

Ensuite, le systeme verifie si le depositId correspond a une facture de commission (pawapay_deposit_ref). Si oui, la facture est marquee comme payee et le bailleur recoit une notification.
3

Paiement de loyer

Si aucune correspondance n’est trouvee, le paiement est traite comme un loyer classique. Le systeme recherche le bail associe via la cle Redis pawapay_pending:{depositId}.

​
Idempotence et gestion des doublons

Locayo garantit que chaque paiement n’est traite qu’une seule fois, meme si PawaPay envoie le meme callback plusieurs fois :
  • Cle unique : chaque transaction est identifiee par son depositId (UUID genere par Locayo a l’initiation)
  • Verification en base : avant d’enregistrer un paiement, Celery verifie qu’aucun paiement avec le meme mobile_money_ref n’existe deja
  • Traitement unique : si un doublon est detecte, le traitement est silencieusement ignore (return sans erreur)
L’idempotence est essentielle car PawaPay peut renvoyer un callback en cas de timeout reseau ou de retry automatique. Le systeme ne cree jamais de doublon dans l’historique des paiements.

​
Seuls les depots COMPLETED sont traites

Le endpoint webhook ne declenche le traitement Celery que pour les depots au statut COMPLETED. Les autres statuts (PENDING, FAILED, REJECTED) sont enregistres dans les logs mais ne declenchent aucune action.
Statut PawaPayAction Locayo
COMPLETEDTraitement complet : enregistrement, recu, notification
FAILEDLog uniquement. Aucun enregistrement
REJECTEDLog uniquement. Aucun enregistrement

​
Securite

  • Signature RFC-9421 : chaque callback PawaPay est signe cryptographiquement. Locayo verifie la signature avant tout traitement
  • Rate limiting : le endpoint webhook est limite a 20 requetes par minute pour prevenir les abus
  • HTTPS obligatoire : les callbacks PawaPay sont toujours envoyes via HTTPS