Démarrage rapide

Ce guide vous montre comment accepter votre premier paiement mobile money avec SahelPay, en sandbox.

Prérequis

Un accès SahelPay (demander l’accès : l’ouverture de compte se fait sur demande)
Vos clés API de test (sk_test_..., disponibles dans le dashboard)

La sandbox est gratuite. L’accès à la production est soumis à une validation et à un contrat distinct (voir Passer en production).

1. Créer un paiement

Le header X-Idempotency-Key est obligatoire sur POST /v1/payments (400 IDEMPOTENCY_KEY_REQUIRED sinon). Réutilisez la même clé pour un retry : vous obtenez le même paiement, jamais un doublon.

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

import SahelPay from '@sahelpay/sdk';

const sahelpay = new SahelPay({
  secretKey: process.env.SAHELPAY_SECRET_KEY, // sk_test_...
  environment: 'sandbox'
});

const payment = await sahelpay.payments.create({
  amount: 5000,
  currency: 'XOF',
  payment_method: 'ORANGE_MONEY',
  customer_phone: '+22370123456',
  description: 'Commande #123',
  client_reference: 'order-123',
  return_url: 'https://votre-site.com/checkout/return?order=order-123',
  idempotency_key: 'order-123' // obligatoire côté API
});

// Renvoyer payment.redirect_url à votre frontend pour rediriger le client

use SahelPay\SahelPay;

$sahelpay = new SahelPay(getenv('SAHELPAY_SECRET_KEY')); // sk_test_...

$payment = $sahelpay->payments->initiate([
    'amount' => 5000,
    'currency' => 'XOF',
    'provider' => 'ORANGE_MONEY',
    'customer_phone' => '+22370123456',
    'description' => 'Commande #123',
    'client_reference' => 'order-123',
    'return_url' => 'https://votre-site.com/checkout/return?order=order-123',
    'idempotency_key' => 'order-123', // obligatoire côté API
]);

// Rediriger le client vers le checkout
header('Location: ' . $payment->redirect_url);

from sahelpay import Client

sahelpay = Client('sk_test_xxx')

payment = sahelpay.payments.create(
    amount=5000,
    currency='XOF',
    provider='ORANGE_MONEY',
    customer_phone='+22370123456',
    description='Commande #123',
    client_reference='order-123',
    return_url='https://votre-site.com/checkout/return?order=order-123',
    idempotency_key='order-123',  # obligatoire côté API
)

# Rediriger le client vers le checkout
redirect(payment.redirect_url)

Les SDKs demandent hosted_checkout: true par défaut : redirect_url pointe alors vers le checkout hébergé SahelPay. Avec hosted_checkout: false (défaut de l’API brute), SahelPay initie directement le paiement mobile money et redirect_url pointe vers la page de l’opérateur.

2. Rediriger le client

Redirigez le client vers redirect_url. Il valide le paiement sur la page de l’opérateur.

window.location.href = payment.redirect_url;

Deux modes de test : metadata.sahelpay_mock: true (option SDK mock) utilise le simulateur SahelPay et n’appelle pas l’opérateur, tandis que metadata.sandbox: true (option SDK sandbox) appelle l’environnement de test de l’opérateur. Voir le guide de test.

3. Recevoir le webhook

Le webhook est la source de vérité. Ne marquez jamais une commande comme “payée” sans avoir reçu et vérifié 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');

  if (!signature) {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }

  let event;
  try {
    event = sahelpay.webhooks.constructEvent(
      rawBody,
      signature,
      process.env.SAHELPAY_WEBHOOK_SECRET
    );
  } catch {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const { data } = event;

  if (event.event === 'payment.success') {
    // client_reference = votre identifiant de commande
    await updateOrder(data.client_reference, { status: 'paid' });
  }

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

4. Page de retour

Après un paiement confirmé par le serveur (SUCCESS), la page de paiement SahelPay redirige automatiquement le client vers votre return_url après quelques secondes (un lien « Retour au site marchand » reste affiché). Un paiement en attente, échoué ou non vérifié ne déclenche jamais de redirection automatique. SahelPay n’ajoute aucun paramètre à votre return_url : incluez-y votre propre référence de commande. L’URL doit être en https:// et hors des domaines SahelPay, sinon la page de paiement ne propose aucun retour.

// /checkout/return?order=order-123
const orderId = searchParams.get('order');
const payment = await sahelpay.payments.search(orderId); // par client_reference

if (payment?.status === 'SUCCESS') {
  // Afficher "Paiement confirmé"
} else {
  // Afficher "En cours de traitement..."
}

La page de retour sert uniquement à l’UX. Le statut définitif vient toujours du webhook.

Méthode de paiement disponible

Méthode	Type	Description
`ORANGE_MONEY`	Mobile money	Mali

L’alias MOBILE_MONEY est également accepté.

C’est le seul moyen de paiement disponible. Une autre valeur de provider ou de payment_method renvoie 400.

Prochaines étapes

Passer en production

Accès production sur demande

Webhooks

Configurer et sécuriser vos webhooks

Tests

Sandbox opérateur et simulateur SahelPay

SDKs

Installer les SDKs officiels

Kit développeur et logos

Logos, bouton « Payer avec SahelPay », SDKs et template

API Reference

Documentation complète de l’API

Démarrer

Guides

Ressources

Quickstart

Démarrage rapide

Prérequis

1. Créer un paiement

2. Rediriger le client

3. Recevoir le webhook

4. Page de retour

Méthode de paiement disponible

Prochaines étapes

Passer en production

Webhooks

Tests

SDKs

Kit développeur et logos

API Reference

​Démarrage rapide

​Prérequis

​1. Créer un paiement

​2. Rediriger le client

​3. Recevoir le webhook

​4. Page de retour

​Méthode de paiement disponible

​Prochaines étapes

Passer en production

Webhooks

Tests

SDKs

Kit développeur et logos

API Reference

Démarrage rapide

Prérequis

1. Créer un paiement

2. Rediriger le client

3. Recevoir le webhook

4. Page de retour

Méthode de paiement disponible

Prochaines étapes