> ## Documentation Index
> Fetch the complete documentation index at: https://docs.i-pay.money/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 :
```http theme={null}
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 :
```json theme={null}
{
"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 :
```json theme={null}
{
"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é :
```json theme={null}
{
"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}`.