> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sahelpay.ml/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Intégrez SahelPay en 5 minutes
# Démarrage rapide
Ce guide vous montre comment accepter votre premier paiement avec SahelPay.
## Prérequis
* Un compte SahelPay ([créer un compte](https://dashboard.sahelpay.ml/register))
* Vos clés API (disponibles dans le dashboard)
## 1. Créer un paiement
```bash cURL theme={null}
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"
}'
```
```javascript Node.js theme={null}
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;
```
```php PHP theme={null}
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);
```
```python Python theme={null}
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** :
```bash cURL theme={null}
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"
}'
```
```javascript Node.js theme={null}
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'
});
```
```python Python theme={null}
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` :
```javascript theme={null}
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 :
```javascript theme={null}
// 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 :
```javascript theme={null}
// /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
Comprendre le routing automatique
Configurer et sécuriser vos webhooks
Envoyer de l'argent vers Mobile Money
Paiements récurrents
Numéros de test pour le sandbox
Installer les SDKs officiels
Documentation complète de l'API
Portail client self-service