Documentation Webhook FastPay

Cette page détaille l’intégration des webhooks sur FastPay, avec notamment la structure précise des objets transmis lors des appels webhook, conforme à la documentation TypeScript Swagger de notre backend. Les webhooks permettent de recevoir des notifications temps-réel lors des changements d’état des transactions (paiements, transferts, remboursements, etc).

Qu’est-ce qu’un webhook ?

Un webhook est une requête HTTP POST envoyée par FastPay vers une URL de votre choix, quand un événement a lieu (ex : changement de statut d’un paiement), afin de vous notifier et vous permettre de réagir côté serveur sans avoir à interroger l’API.

Comment configurer son webhook ?

Note : La configuration du webhook s’effectue dans les paramètres de la clé API de votre dashboard FastPay.

  1. Connectez-vous à votre dashboard marchand.
  2. Générez ou éditez votre clé API dans la section Paramètres API.
  3. Ajoutez l’URL de réception webhook au niveau du paramètre dédié de votre clé API.
  4. Sauvegardez les modifications.

Info : Votre endpoint doit accepter les requêtes POST en HTTPS.

Exemple de payload webhook réel

{
  "event": "payment.status.changed",
  "data": {
    "id": "trxn_12345",
    "reference": "ORDER_2024001",
    "amount": 15000,
    "status": "COMPLETE",
    "createdAt": 1705301400,
    "beneficiary": "Client Example",
    "service_mobile": "Orange Money",
    "organisation": "Top Marchand",
    "extra_data": {
      "order_id": "2024001",
      "custom_field": "exemple"
    }
  }
}

Liste des événements Webhook

ValeurDescription
transaction.createdUne transaction vient d’être créée
transaction.startedLe traitement de la transaction a démarré
transaction.completedLa transaction a été complétée
transaction.failedLa transaction a échoué

Comportement d'attente

  • Vous devez retourner une réponse HTTP 2xx pour accuser l’intégration correcte.
  • En cas d’erreur ou de timeout, FastPay réessaiera périodiquement l’envoi.

Bonnes Pratiques

  • Traitez le webhook de façon rapide (<5s recommandé).
  • Privilégiez un traitement asynchrone pour les étapes longues.
  • Logguez tous les payloads reçus pour analyse et audit.
  • Filtrez bien les événements par status de transaction et event.

FAQ

  • Comment tester les webhooks ? Utilisez votre dashboard sandbox en configurant l’URL de test et effectuez des opérations factices.
  • Combien d’URL webhook ? Une seule URL webhook par environnement (production/sandbox) et par clé API.

Support

Une question sur les webhooks FastPay ?

FastPay API Reference
Complete API documentation for FastPay payment aggregator
Get Payments by API Key
Retrieve payments for an API key with filtering