Skip to main content
POST
/
v1
/
payments
Créer un paiement
curl --request POST \
  --url https://api.example.com/v1/payments

​
Créer un paiement

Crée une nouvelle intention de paiement et retourne une URL de redirection vers le checkout.

​
Endpoint

POST /v1/payments

​
Headers

HeaderRequisDescription
Authorization✅Bearer sk_xxx
Content-Type✅application/json
X-Idempotency-KeyRecommandéClé unique pour éviter les doublons

​
Body

ParamètreTypeRequisDescription
amountinteger✅Montant en FCFA (min: 100)
currencystringDevise (défaut: XOF)
payment_methodstring✅ORANGE_MONEY, WAVE, MOOV, CARD, VISA, MASTERCARD, GIM_UEMOA
countrystringCode pays: ML, SN, CI
customer_phonestring✅Numéro de téléphone (+223…)
customer_namestring✅ pour CARDNom du client (requis pour cartes)
customer_emailstring✅ pour CARDEmail du client (requis pour cartes)
return_urlstring✅URL de retour après paiement
client_referencestringVotre référence (order_id)
metadataobjectDonnées personnalisées

​
Exemple

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",
    "customer_name": "Amadou Diallo",
    "return_url": "https://votre-site.com/checkout/return",
    "client_reference": "order_123",
    "metadata": {
      "order_id": "order_123"
    }
  }'

​
Réponse

{
  "success": true,
  "data": {
    "id": "txn_abc123def456",
    "status": "PENDING",
    "amount": 5000,
    "currency": "XOF",
    "payment_method": "ORANGE_MONEY",
    "redirect_url": "https://pay.sahelpay.ml/checkout/txn_abc123def456",
    "gateway_used": "internal_gateway_id",
    "routing_reason": "Routing optimisé pour coût et disponibilité",
    "expires_at": "2025-12-18T17:00:00.000Z",
    "created_at": "2025-12-18T16:45:00.000Z"
  }
}

​
Champs de routing

ChampDescription
gateway_usedIdentifiant technique interne (pour monitoring uniquement)
routing_reasonExplication du routing choisi par SahelPay
Ces champs sont informatifs. SahelPay choisit automatiquement le meilleur gateway selon le coût et la disponibilité. Voir le guide Smart Routing pour plus de détails.

## Erreurs

| Code | Description |
|------|-------------|
| `INVALID_AMOUNT` | Montant invalide (< 100 ou > 5M) |
| `MISSING_PHONE` | Numéro de téléphone requis |
| `MISSING_RETURN_URL` | URL de retour requise |
| `DUPLICATE_PAYMENT` | Paiement déjà créé (idempotence) |