Skip to main content

​
Démarrage rapide

Ce guide vous montre comment accepter votre premier paiement avec SahelPay.

​
Prérequis

  • Un compte SahelPay (créer un compte)
  • Vos clés API (disponibles dans le dashboard)

​
1. Créer un paiement

curl -X POST https://api.sahelpay.ml/v1/payments \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "payment_method": "ORANGE_MONEY",
    "country": "ML",
    "customer_phone": "+22370123456",
    "return_url": "https://votre-site.com/checkout/return"
  }'

​
Paiement par Carte Bancaire

Pour les paiements par carte, les champs customer_name et customer_email sont requis : 
curl -X POST https://api.sahelpay.ml/v1/payments \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "XOF",
    "payment_method": "CARD",
    "customer_phone": "+22370123456",
    "customer_name": "Mamadou Diallo",
    "customer_email": "[email protected]",
    "return_url": "https://votre-site.com/checkout/return"
  }'
Pour les paiements par carte (CARD, VISA, MASTERCARD, GIM_UEMOA), customer_name et customer_email sont obligatoires.

​
2. Rediriger le client

Après la création, redirigez le client vers redirect_url : 
window.location.href = payment.redirectUrl;
Le client sera redirigé vers la page de checkout SahelPay où il pourra choisir son mode de paiement.

​
3. Recevoir le webhook

Le webhook est la source de vérité. Ne marquez jamais une commande comme “payée” sans avoir reçu le webhook payment.success.
Configurez votre endpoint webhook dans le dashboard, puis implémentez le handler : 
// POST /api/webhooks/sahelpay
export async function POST(request) {
  const rawBody = await request.text();
  const signature = request.headers.get('x-sahelpay-signature');

  // Vérifier la signature
  const isValid = sahelpay.verifyWebhook(rawBody, signature);
  if (!isValid) {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const { event, data } = JSON.parse(rawBody);

  if (event === 'payment.success') {
    // Marquer la commande comme payée
    await updateOrder(data.metadata.order_id, { status: 'paid' });
  }

  return Response.json({ received: true });
}

​
4. Page de retour

Quand le client revient sur votre site via return_url, affichez un message de confirmation : 
// /checkout/return?payment_intent_id=xxx
const paymentId = searchParams.get('payment_intent_id');
const status = await sahelpay.getPaymentStatus(paymentId);

if (status.status === 'SUCCESS') {
  // Afficher "Paiement confirmé"
} else if (status.status === 'PENDING') {
  // Afficher "En cours de traitement..."
}
La page de retour sert uniquement à l’UX. Le statut définitif vient toujours du webhook.

​
Méthodes de paiement disponibles

MéthodeTypeDescription
ORANGE_MONEYMobile MoneyOrange Money (Mali, Sénégal, CI)
WAVEMobile MoneyWave (Mali, Sénégal, CI)
MOOVMobile MoneyMoov Money (Mali, Bénin, Togo)
CARDCarteCarte bancaire générique (VISA/MC/GIM)
VISACarteCarte VISA
MASTERCARDCarteCarte Mastercard
GIM_UEMOACarteCarte régionale GIM-UEMOA
SahelPay utilise un Smart Routing automatique. Vous spécifiez la méthode de paiement et SahelPay choisit le meilleur provider en interne selon le coût et la disponibilité.

​
Prochaines étapes

Smart Routing

Comprendre le routing automatique

Webhooks

Configurer et sécuriser vos webhooks

Payouts

Envoyer de l’argent vers Mobile Money

Subscriptions

Paiements récurrents

Test Accounts

Numéros de test pour le sandbox

SDKs

Installer les SDKs officiels

API Reference

Documentation complète de l’API

Customer Portal

Portail client self-service