Webhooks

Les webhooks permettent à iPayMoney d’envoyer automatiquement une notification à votre application lorsqu’un paiement change d’état. Vous pouvez les utiliser pour mettre à jour une commande, synchroniser un back-office ou déclencher un traitement interne sans interroger l’API en continu.

Créer un webhook

Depuis le tableau de bord marchand, ouvrez Développeurs, puis Webhooks. Cliquez ensuite sur Ajouter pour enregistrer un nouveau webhook.

Le formulaire demande les informations suivantes :

Champ	Description
URL	URL de votre endpoint de réception. Si le protocole n’est pas renseigné, iPayMoney ajoute automatiquement https://.
Hash secret	Valeur secrète envoyée dans l’en-tête HTTP Secret-Hash à chaque notification.
Événements créés	Active les notifications payment_created.
Événements en attente	Active les notifications payment_pending.
Événements réussis	Active les notifications payment_succeeded.
Événements échoués	Active les notifications payment_failed.
Événements remboursés	Active les notifications payment_refunded.

Vous pouvez activer un ou plusieurs événements sur le même webhook. Seuls les événements cochés seront envoyés à l’URL configurée.

Le champ Hash secret doit contenir la valeur que votre serveur comparera à l’en-tête Secret-Hash. Le mécanisme actuel transmet cette valeur telle quelle : il ne calcule pas une signature HMAC du corps JSON.

Attention : ne partagez jamais le hash secret de votre webhook. Il permet à votre serveur de vérifier que la notification provient bien de iPayMoney.

Après avoir choisi les événements à recevoir, cliquez sur Enregistrer.

Recevoir une notification

Lorsqu’un événement actif se produit, iPayMoney envoie une requête POST vers votre URL avec un corps JSON et les en-têtes suivants :

Content-Type: application/json
Accept: application/json
Secret-Hash: votre_hash_secret

Votre endpoint doit vérifier la valeur de Secret-Hash, traiter le corps JSON, puis retourner une réponse HTTP 2xx lorsque la notification est bien reçue. Les réponses hors 2xx et les erreurs réseau sont enregistrées dans l’historique du webhook.

Attention : ne considérez pas le webhook comme l’unique preuve d’un paiement et ne supposez pas qu’un envoi échoué sera rejoué jusqu’au succès. Conservez la référence et utilisez l’endpoint de vérification pour la réconciliation.

Événements disponibles

Événement	Quand il est envoyé
payment_created	Le paiement vient d’être créé.
payment_pending	Le paiement passe à l’état en attente.
payment_succeeded	Le paiement est validé avec succès.
payment_failed	Le paiement échoue.
payment_refunded	Le paiement est remboursé.

Format du payload

Toutes les notifications utilisent la même structure de base :

{
  "data": {
    "external_reference": "ORDER-2026-001",
    "reference": "ipay_ref_123",
    "status": "succeeded",
    "msisdn": "97000000",
    "net_amount": 950,
    "amount": 1000,
    "failure_reason": null,
    "customer_name": "Client Demo",
    "payment_method": "credit_card",
    "validated_at": "2026-06-04T10:30:00.000Z"
  }
}

Champs du payload

Champ	Description
external_reference	Référence envoyée par votre système lors de la création du paiement.
reference	Référence interne iPayMoney du paiement.
status	Statut actuel du paiement : initiated, pending, succeeded, failed ou refunded.
msisdn	Numéro de paiement du client.
amount	Montant brut du paiement.
net_amount	Montant net après frais.
failure_reason	Raison de l’échec lorsque le paiement a échoué.
customer_name	Nom du client lorsque l’information est disponible.
payment_method	Méthode de paiement utilisée.
validated_at	Date de validation du paiement lorsque disponible.

Selon l’origine du paiement, iPayMoney peut aussi ajouter :

Champ optionnel	Description
dynamic_payment_reference	Référence du paiement dynamique associé.
external_payment_reference	Référence du paiement externe associé.

Exemples de payloads

Paiement réussi :

{
  "data": {
    "external_reference": "ORDER-1001",
    "reference": "yeweyk6rd7cm",
    "status": "succeeded",
    "msisdn": "97000001",
    "net_amount": 950,
    "amount": 1000,
    "failure_reason": null,
    "customer_name": "Client Demo",
    "payment_method": "credit_card",
    "validated_at": "2026-06-04T10:30:00.000Z"
  }
}

Paiement échoué :

{
  "data": {
    "external_reference": "ORDER-1002",
    "reference": "zug596nsydoh",
    "status": "failed",
    "msisdn": "97000003",
    "net_amount": 0,
    "amount": 1000,
    "failure_reason": "Paiement refusé",
    "customer_name": "Client Demo",
    "payment_method": "amana",
    "validated_at": null
  }
}

Consulter l’historique

La page Webhooks affiche les webhooks configurés avec leur URL, les événements actifs, leur date de création et les actions disponibles.

Pour chaque webhook, le bouton Logs permet de consulter l’historique des notifications envoyées. L’historique affiche :

• la référence du paiement ;
• l’événement envoyé ;
• le statut HTTP retourné par votre serveur ;
• le corps de la requête envoyée ;
• la réponse retournée par votre serveur ;
• la date d’envoi.

Le détail d’un log permet de vérifier le payload complet et les informations du paiement concerné.

Bonnes pratiques

• Utilisez une URL HTTPS publique et stable.
• Vérifiez toujours l’en-tête Secret-Hash avant de traiter la notification.
• Retournez rapidement une réponse HTTP 2xx après réception.
• Rendez votre traitement idempotent en utilisant la référence iPayMoney reference.
• Ne dépendez pas de l’ordre exact des notifications : vérifiez toujours le status du paiement reçu.
• Acceptez qu’une notification puisse être reçue plusieurs fois ou ne pas parvenir à votre serveur.
• Réconciliez les paiements restés en attente avec GET /api/v1/payments/{reference}.