Webhooks (IPN)¶

M-Pay reçoit automatiquement les notifications de paiement (IPN) du prestataire et met à jour les statuts en temps réel. Ce guide explique le fonctionnement et comment intégrer les notifications dans votre PMS.

Fonctionnement¶

Client paie
    │
    ▼
PayZen traite ──► IPN envoyée à M-Pay
                       │
                       ▼
                  Vérification HMAC-SHA256
                       │
                       ▼
                  Mise à jour du PaymentRequest
                       │
                       ▼
                  Email de confirmation (si activé)
                       │
                       ▼
                  Votre PMS consulte le statut (polling)

Endpoint IPN¶

L'endpoint IPN est configuré dans votre back-office PayZen :

https://votre-domaine.com/payment/ipn/

Sécurité¶

Vérification HMAC-SHA256¶

Chaque notification est vérifiée via une signature HMAC-SHA256 :

1. PayZen envoie kr-answer (données) et kr-hash (signature)
2. M-Pay recalcule le hash avec la clé HMAC du tenant
3. Comparaison timing-safe pour éviter les attaques temporelles
4. Si la signature est invalide, la notification est rejetée (HTTP 400)

Protection anti-replay¶

• Les notifications sont traitées de manière idempotente
• Un paiement déjà en statut terminal ne peut pas être modifié

Intégration avec votre PMS¶

Option 1 : Polling régulier (recommandé)¶

La méthode la plus simple. Votre PMS interroge régulièrement l'API M-Pay :

# Toutes les 5 minutes via un cron/scheduler
statuses = sync_payment_statuses(pending_reservation_refs)
for ref, data in statuses.items():
    update_pms_reservation(ref, data["status"])

Option 2 : Webhook sortant (futur)¶

Statuts reçus par IPN¶

Données extraites de l'IPN¶

À chaque notification, M-Pay extrait et stocke :