Guide d’intégration
Ce guide détaille le flow complet d’intégration SahelPay pour une application marchande.Principes fondamentaux
Architecture
Flow détaillé
1. Créer le paiement (backend)
client_reference est renvoyé dans chaque webhook et sert à GET /v1/payments/search. C’est la clé la plus simple pour relier un paiement à votre commande. Les metadata personnalisées ne sont pas recopiées dans les webhooks (seuls description et marketplace le sont).2. Rediriger le client
3. Recevoir le webhook
4. Page de retour
Après un paiement confirmé (SUCCESS), la page de paiement SahelPay redirige automatiquement le client vers votre return_url (HTTPS, hors domaines SahelPay). Aucun paramètre n’est ajouté : mettez votre référence de commande dans l’URL. Les paiements en attente ou échoués ne redirigent pas automatiquement.
Idempotence
Côté création
X-Idempotency-Key est obligatoire sur POST /v1/payments (128 caractères maximum). Basez-le sur votre commande :
- Même clé + même demande : SahelPay renvoie le paiement déjà créé.
- Même clé + demande différente (montant, devise, téléphone, mode test/live) : erreur HTTP
409.
Côté webhook
Dédupliquez surid du payload (identique au header X-SahelPay-Event-ID), puis vérifiez l’état de la commande avant de la mettre à jour.
Ce que votre app NE DOIT PAS faire
❌ Appeler l’opérateur directement
Passez toujours par SahelPay
❌ Recalculer les montants
Utilisez les montants renvoyés par l’API
❌ Agir pour des tiers
L’API n’est pas un service de collecte pour d’autres vendeurs
❌ Marquer PAID sans webhook
Le return_url est pour l’UX uniquement