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",
    "metadata": { "sandbox": true }
  }'

import SahelPay from '@sahelpay/sdk';

const sahelpay = new SahelPay({
  secretKey: 'sk_test_xxx',
  environment: 'sandbox'
});

const payment = await sahelpay.payments.create({
  amount: 5000,
  currency: 'XOF',
  payment_method: 'ORANGE_MONEY',
  customer_phone: '+22370123456',
  description: 'Commande #123',
  return_url: 'https://votre-site.com/checkout/return',
  sandbox: true
});

// Rediriger le client vers Orange Money
window.location.href = payment.redirect_url;

use SahelPay\SahelPay;

$sahelpay = new SahelPay('sk_test_xxx');

$payment = $sahelpay->payments->initiate([
    'amount' => 5000,
    'currency' => 'XOF',
    'provider' => 'ORANGE_MONEY',
    'customer_phone' => '+22370123456',
    'description' => 'Commande #123',
    'return_url' => 'https://votre-site.com/checkout/return',
    'sandbox' => true
]);

// Rediriger le client vers Orange Money
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',
    return_url='https://votre-site.com/checkout/return',
    sandbox=True,
)

# Rediriger le client vers Orange Money
redirect(payment.redirect_url)

2. Rediriger le client

Après la création, redirigez le client vers redirect_url :

window.location.href = payment.redirect_url;

Le client sera redirigé vers la page de checkout SahelPay où il pourra choisir son mode de paiement.

Deux modes de test : metadata.sahelpay_mock: true utilise le simulateur SahelPay et n’appelle pas l’opérateur, tandis que metadata.sandbox: true appelle bien l’environnement de test d’Orange. 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 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') {
    // 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 result = await sahelpay.payments.checkStatus(paymentId);

if (result.status === 'SUCCESS') {
  // Afficher "Paiement confirmé"
} else if (result.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éthode	Type	Description
`ORANGE_MONEY`	Mobile Money	Orange Money (Mali)

Les alias ORANGE et MOBILE_MONEY sont acceptés et résolus vers ORANGE_MONEY.

Orange Money est le seul rail intégré. Une autre valeur de provider renvoie 400. Voir Méthodes de paiement pour interroger la liste des rails activés plutôt que de la coder en dur.

Prochaines étapes

Méthodes de paiement

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

Getting Started

Guides

Resources

Quickstart

Démarrage rapide

Prérequis

1. Créer un paiement

2. Rediriger le client

3. Recevoir le webhook

4. Page de retour

Méthodes de paiement disponibles

Prochaines étapes

Méthodes de paiement

Webhooks

Payouts

Subscriptions

Test Accounts

SDKs

API Reference

Customer Portal

​Démarrage rapide

​Prérequis

​1. Créer un paiement

​2. Rediriger le client

​3. Recevoir le webhook

​4. Page de retour

​Méthodes de paiement disponibles

​Prochaines étapes

Méthodes de paiement

Webhooks

Payouts

Subscriptions

Test Accounts

SDKs

API Reference

Customer Portal

Démarrage rapide

Prérequis

1. Créer un paiement

2. Rediriger le client

3. Recevoir le webhook

4. Page de retour

Méthodes de paiement disponibles

Prochaines étapes