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"
  }'

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'
});

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

use SahelPay\SahelPay;

$sahelpay = new SahelPay('sk_test_xxx');

$payment = $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'
]);

// 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'
)

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

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": "mamadou@example.com",
    "return_url": "https://votre-site.com/checkout/return"
  }'

const payment = await sahelpay.payments.create({
  amount: 10000,
  currency: 'XOF',
  payment_method: 'CARD',
  customer_phone: '+22370123456',
  customer_name: 'Mamadou Diallo',      // Requis pour CARD
  customer_email: 'mamadou@example.com', // Requis pour CARD
  return_url: 'https://votre-site.com/checkout/return'
});

payment = sahelpay.payments.create(
    amount=10000,
    currency='XOF',
    provider='CARD',
    customer_phone='+22370123456',
    customer_name='Mamadou Diallo',       # Requis
    customer_email='mamadou@example.com', # Requis
    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éthode	Type	Description
`ORANGE_MONEY`	Mobile Money	Orange Money (Mali, Sénégal, CI)
`WAVE`	Mobile Money	Wave (Mali, Sénégal, CI)
`MOOV`	Mobile Money	Moov Money (Mali, Bénin, Togo)
`CARD`	Carte	Carte bancaire générique (VISA/MC/GIM)
`VISA`	Carte	Carte VISA
`MASTERCARD`	Carte	Carte Mastercard
`GIM_UEMOA`	Carte	Carte 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

Getting Started

Guides

Resources

Quickstart

Démarrage rapide

Prérequis

1. Créer un paiement

Paiement par Carte Bancaire

2. Rediriger le client

3. Recevoir le webhook

4. Page de retour

Méthodes de paiement disponibles

Prochaines étapes

Smart Routing

Webhooks

Payouts

Subscriptions

Test Accounts

SDKs

API Reference

Customer Portal

​Démarrage rapide

​Prérequis

​1. Créer un paiement

​Paiement par Carte Bancaire

​2. Rediriger le client

​3. Recevoir le webhook

​4. Page de retour

​Méthodes de paiement disponibles

​Prochaines étapes

Smart Routing

Webhooks

Payouts

Subscriptions

Test Accounts

SDKs

API Reference

Customer Portal

Démarrage rapide

Prérequis

1. Créer un paiement

Paiement par Carte Bancaire

2. Rediriger le client

3. Recevoir le webhook

4. Page de retour

Méthodes de paiement disponibles

Prochaines étapes