Skip to main content

Guide d’intégration

Ce guide détaille le flow complet d’intégration SahelPay pour une application marchande.

Principes fondamentaux

Règles non négociables :
  • Votre app utilise l’API SahelPay pour son propre usage : elle n’agit pas pour le compte de tiers
  • Les montants font foi tels que renvoyés par l’API : ne les recalculez pas côté client
  • Le webhook est la seule source de vérité pour le statut d’un paiement

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

Le client valide auprès de l’opérateur. Si la page est rechargée ou si le client clique deux fois sur « Payer », le checkout reprend la même session de paiement au lieu d’en créer une nouvelle.

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 sur id 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