Documentation API ElyonPay

Bienvenue dans la documentation technique de l'API ElyonPay. Cette référence vous permet d'intégrer les paiements Mobile Money, Visa, Mastercard et virements dans votre application en quelques lignes de code.

URL de base : https://api.elyonpay.com/v1
Toutes les requêtes doivent être envoyées en HTTPS. Les requêtes HTTP non sécurisées sont refusées.

Fonctionnalités clés

🌍 Mobile Money unifié — MTN MoMo, Orange Money, Wave, Moov, Airtel Money
💳 Cartes bancaires — Visa, Mastercard avec 3D Secure, conformité PCI DSS niveau 1
🔔 Webhooks temps réel — notifications instantanées pour chaque événement
🧪 Sandbox complet — testez sans frais avec des données simulées
🌐 Multi-devises — XAF, XOF, EUR, USD, GBP, NGN, CDF, KES
📦 SDKs officiels — JavaScript, PHP, Python, Java, React Native

Démarrage rapide

Suivez ces 3 étapes pour effectuer votre premier paiement :

Créez un compte sur app.elyonpay.com et obtenez votre clé API
Installez le SDK de votre langage ou utilisez cURL directement
Appelez POST /v1/payments avec le montant, la devise et la méthode de paiement

cURL

curl -X POST https://api.elyonpay.com/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "XAF",
    "method": "mtn_mobile_money",
    "phone": "+237600000000",
    "description": "Commande #1234",
    "callback_url": "https://yoursite.com/webhook"
  }'

Authentification

L'API ElyonPay utilise des clés API avec le schéma d'authentification Bearer Token. Chaque compte dispose d'une clé de test et d'une clé de production.

Vos clés API

Type	Préfixe	Environnement	Usage
test	`sk_test_...`	Sandbox	Développement & tests — aucun débit réel
live	`sk_live_...`	Production	Transactions réelles — à garder secrète

Utilisation dans l'en-tête HTTP

HTTP Header

Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

Sécurité : Ne jamais exposer votre clé API côté client (JavaScript navigateur). Effectuez toujours les appels depuis votre serveur backend.

Environnements

ElyonPay propose deux environnements distincts pour vous permettre de développer et tester en toute sécurité avant la mise en production.

URLs de base

Environnement	URL de base	Description
`Sandbox`	`https://api.elyonpay.com/v1` (clé `sk_test_`)	Aucun débit réel — données simulées
`Production`	`https://api.elyonpay.com/v1` (clé `sk_live_`)	Transactions réelles

L'environnement est déterminé automatiquement par le type de clé API utilisée. Il n'est pas nécessaire de changer l'URL.

Numéros de test Mobile Money

Numéro	Réseau	Comportement simulé
`+237600000001`	MTN MoMo	✅ Paiement réussi
`+237600000002`	MTN MoMo	❌ Solde insuffisant
`+237690000001`	Orange Money	✅ Paiement réussi
`+237690000002`	Orange Money	⏱ Timeout simulé
`+221700000001`	Wave	✅ Paiement réussi

Format des requêtes

Toutes les requêtes et réponses utilisent le format JSON. L'en-tête Content-Type: application/json est obligatoire pour les requêtes avec un body.

En-têtes requis

En-tête	Valeur	Obligatoire
`Authorization`	`Bearer {votre_cle_api}`	Requis
`Content-Type`	`application/json`	Requis (POST)
`Accept`	`application/json`	Optionnel
`Idempotency-Key`	UUID unique	Recommandé

Format de réponse standard

JSON — Réponse succès

{
  "success": true,
  "data": {
    "id": "pay_1A2B3C4D5E6F",
    "status": "pending",
    "amount": 15000,
    "currency": "XAF"
  },
  "meta": {
    "request_id": "req_xxxxxxx",
    "timestamp": "2024-03-24T10:15:00Z"
  }
}

Créer un paiement

Initie une transaction de paiement vers un client via Mobile Money ou carte bancaire.

POST /v1/payments Initier un paiement

Paramètres du body

Paramètre	Type	Requis	Description
amount	integer	Requis	Montant en unité de la devise (ex: centimes pour EUR, entier pour XAF)
currency	string	Requis	Code ISO 4217 : `XAF`, `XOF`, `EUR`, `USD`, `GBP`
method	string	Requis	`mtn_mobile_money` · `orange_money` · `wave` · `moov_money` · `airtel_money` · `card`
phone	string	Mobile Money	Numéro au format international : `+237600000000`
description	string	Optionnel	Libellé visible par le client (max 255 caractères)
callback_url	string	Optionnel	URL HTTPS pour recevoir le webhook de confirmation
metadata	object	Optionnel	Données libres associées au paiement (order_id, customer_id…)

Exemple — JavaScript (Node.js)

JavaScript / Node.js

// npm install elyonpay-sdk
const ElyonPay = require('elyonpay-sdk');
const client = new ElyonPay('sk_test_xxxxxxxxxx');

const payment = await client.payments.create({
  amount:       15000,
  currency:     'XAF',
  method:       'mtn_mobile_money',
  phone:        '+237600000001',
  description:  'Commande #1234',
  callback_url: 'https://yoursite.com/webhook/elyonpay',
  metadata:     { order_id: 'ORD-1234', customer_id: 'USR-567' }
});

console.log(payment.id);      // pay_1A2B3C4D5E6F
console.log(payment.status);  // pending

PHP

// composer require elyonpay/php-sdk
require_once 'vendor/autoload.php';
use ElyonPay\Client;

$client = new Client('sk_test_xxxxxxxxxx');

$payment = $client->payments->create([
  'amount'       => 15000,
  'currency'     => 'XAF',
  'method'       => 'orange_money',
  'phone'        => '+237690000001',
  'description'  => 'Commande #1234',
  'callback_url' => 'https://yoursite.com/webhook'
]);

echo $payment->id;      // pay_1A2B3C4D5E6F
echo $payment->status;  // pending

Python

# pip install elyonpay
import elyonpay

client = elyonpay.Client('sk_test_xxxxxxxxxx')

payment = client.payments.create(
  amount=15000,
  currency='XAF',
  method='mtn_mobile_money',
  phone='+237600000001',
  description='Commande #1234',
  callback_url='https://yoursite.com/webhook'
)

print(payment.id)      # pay_1A2B3C4D5E6F
print(payment.status)  # pending

cURL

curl -X POST https://api.elyonpay.com/v1/payments \
  -H "Authorization: Bearer sk_test_xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000, "currency": "XAF",
    "method": "mtn_mobile_money",
    "phone": "+237600000001",
    "description": "Commande #1234"
  }'

Statut d'un paiement

GET /v1/payments/{id} Récupère un paiement par son ID

Paramètre de chemin

Paramètre	Type	Description
id	string	Identifiant du paiement, ex : `pay_1A2B3C4D5E6F`

JSON — Réponse

{
  "success": true,
  "data": {
    "id": "pay_1A2B3C4D5E6F",
    "status": "successful",
    "amount": 15000,
    "currency": "XAF",
    "method": "mtn_mobile_money",
    "phone": "+237600000001",
    "description": "Commande #1234",
    "created_at": "2024-03-24T10:15:00Z",
    "paid_at": "2024-03-24T10:15:42Z",
    "metadata": { "order_id": "ORD-1234" }
  }
}

Liste des paiements

GET /v1/payments Liste paginée des paiements

Paramètres de requête (query)

Paramètre	Type	Défaut	Description
page	integer	`1`	Numéro de page
limit	integer	`20`	Résultats par page (max 100)
status	string	—	Filtrer par statut : `pending`, `successful`, `failed`
from	date	—	Date de début ISO 8601 : `2024-01-01`
to	date	—	Date de fin ISO 8601

Remboursements

POST /v1/refunds Rembourser un paiement

Paramètre	Type	Requis	Description
payment_id	string	Requis	ID du paiement à rembourser
amount	integer	Optionnel	Montant partiel (si omis : remboursement total)
reason	string	Optionnel	Motif du remboursement

Les remboursements Mobile Money sont traités sous 24 à 72 heures selon l'opérateur. Les remboursements carte sont effectués sous 5 à 10 jours ouvrés.

Virements (Payouts)

Envoyez des fonds depuis votre solde ElyonPay vers un compte Mobile Money ou bancaire.

POST /v1/payouts Initier un virement sortant

Paramètre	Type	Requis	Description
amount	integer	Requis	Montant à virer
currency	string	Requis	Devise : `XAF`, `XOF`, `EUR`…
method	string	Requis	`mtn_mobile_money`, `orange_money`, `bank_transfer`
phone	string	Mobile Money	Numéro destinataire
description	string	Optionnel	Référence du virement

Solde du compte

GET /v1/balance Consulte le solde disponible

JSON — Réponse

{
  "success": true,
  "data": {
    "available": { "XAF": 850000, "EUR": 1290 },
    "pending":   { "XAF": 125000, "EUR": 0 }
  }
}

Liste des transactions

GET /v1/transactions Historique complet des mouvements

Retourne tous les mouvements de compte : paiements reçus, remboursements, virements, frais. Mêmes filtres que /v1/payments (page, limit, from, to).

SDKs officiels

Des SDKs officiels sont disponibles pour les principaux langages et frameworks. Ils gèrent automatiquement l'authentification, les erreurs et les webhooks.

🟨

JavaScript

npm install elyonpay-sdk

🐘

PHP

composer require elyonpay/php-sdk

npm install @elyonpay/rn

🎯

Flutter

pub add elyonpay_flutter

Webhooks

ElyonPay envoie des notifications HTTP POST à votre callback_url à chaque événement important. Configurez vos webhooks depuis votre tableau de bord.

Événements disponibles

payment.successfulPaiement confirmé et fonds reçus
payment.failedPaiement échoué (solde insuffisant, timeout…)
payment.pendingPaiement en attente de confirmation opérateur
refund.successfulRemboursement effectué avec succès
payout.successfulVirement sortant exécuté
payout.failedVirement sortant échoué
balance.lowSolde sous le seuil configuré

Structure du payload webhook

JSON — Payload webhook

{
  "event": "payment.successful",
  "created_at": "2024-03-24T10:15:42Z",
  "data": {
    "id": "pay_1A2B3C4D5E6F",
    "amount": 15000,
    "currency": "XAF",
    "status": "successful",
    "metadata": { "order_id": "ORD-1234" }
  },
  "signature": "sha256=abcdef1234567890..."
}

Vérifiez toujours la signature X-ElyonPay-Signature dans l'en-tête HTTP pour authentifier les webhooks. Comparez avec HMAC-SHA256(payload, votre_webhook_secret).

Mobile Money

ElyonPay unifie 5 réseaux Mobile Money africains sous une seule API. Chaque réseau possède ses propres codes opérateurs et pays de couverture.

Réseaux supportés

Code méthode	Réseau	Pays	Devises
`mtn_mobile_money`	MTN MoMo	🇨🇲 CM · 🇳🇬 NG · 🇨🇮 CI · 🇬🇭 GH · 🇺🇬 UG	XAF · NGN · XOF
`orange_money`	Orange Money	🇨🇲 CM · 🇨🇮 CI · 🇸🇳 SN · 🇲🇱 ML	XAF · XOF
`wave`	Wave	🇸🇳 SN · 🇨🇮 CI · 🇧🇫 BF · 🇲🇱 ML	XOF
`moov_money`	Moov Africa	🇧🇯 BJ · 🇹🇬 TG · 🇧🇫 BF · 🇳🇪 NE	XOF
`airtel_money`	Airtel Money	🇰🇪 KE · 🇹🇿 TZ · 🇺🇬 UG · 🇿🇲 ZM · 🇨🇩 CD	KES · TZS · UGX · CDF

Cartes bancaires

Acceptez les paiements Visa et Mastercard avec 3D Secure, tokenisation et conformité PCI DSS niveau 1.

Cartes de test (Sandbox)

Numéro de carte	Expiration	CVV	Comportement
`4242 4242 4242 4242`	12/28	123	✅ Paiement réussi
`4000 0000 0000 0002`	12/28	123	❌ Carte refusée
`4000 0000 0000 3220`	12/28	123	🔐 3D Secure requis
`5555 5555 5555 4444`	12/28	123	✅ Mastercard réussi

Statuts des paiements

Chaque paiement passe par plusieurs statuts au cours de son cycle de vie.

pending

En attente de confirmation opérateur

successful

Paiement confirmé, fonds reçus

failed

Paiement échoué ou refusé

refunded

Remboursement effectué

cancelled

Annulé avant traitement

expired

Délai de paiement dépassé

Codes d'erreur

En cas d'erreur, l'API retourne un objet JSON avec un code d'erreur machine et un message lisible.

JSON — Réponse erreur

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Le solde Mobile Money du client est insuffisant.",
    "http_status": 402
  }
}

Table des erreurs

Code erreur	HTTP	Description
UNAUTHORIZED	401	Clé API manquante ou invalide
INVALID_AMOUNT	400	Montant invalide ou inférieur au minimum autorisé
CURRENCY_NOT_SUPPORTED	400	Devise non supportée pour ce réseau
PHONE_INVALID	400	Numéro de téléphone invalide ou non enregistré
INSUFFICIENT_FUNDS	402	Solde insuffisant côté client
OPERATOR_TIMEOUT	408	L'opérateur Mobile Money n'a pas répondu dans les délais
DUPLICATE_REQUEST	409	Requête dupliquée — utiliser Idempotency-Key
PAYMENT_NOT_FOUND	404	Paiement introuvable
RATE_LIMIT_EXCEEDED	429	Trop de requêtes — réessayez dans quelques secondes
INTERNAL_ERROR	500	Erreur interne ElyonPay — contactez le support

Devises supportées

Code	Devise	Montant minimum	Méthodes
`XAF`	Franc CFA BEAC	100 XAF	MTN MoMo, Orange Money, Carte
`XOF`	Franc CFA BCEAO	100 XOF	Wave, Moov, Orange Money, MTN, Carte
`EUR`	Euro	0,50 €	Carte (Visa, Mastercard), PayPal
`USD`	Dollar américain	0,50 $	Carte, PayPal, Stripe
`GBP`	Livre sterling	0,30 £	Carte
`NGN`	Naira nigérian	100 NGN	MTN MoMo NG
`KES`	Shilling kenyan	10 KES	Airtel Money
`CDF`	Franc congolais	500 CDF	Airtel Money

Sandbox & Tests

L'environnement sandbox vous permet de tester l'intégration complète sans effectuer de vrais paiements. Utilisez votre clé sk_test_ — aucun débit réel ne sera effectué.

Accédez au tableau de bord sandbox sur app.elyonpay.com pour visualiser vos transactions de test en temps réel.

Limites du sandbox

Les transactions sandbox n'engendrent aucuns frais
Les webhooks sandbox sont envoyés avec un délai de 2 à 5 secondes
Les données sont réinitialisées tous les 30 jours
Limite de 1 000 requêtes/heure par clé test

Passer en production

Complétez la vérification KYB (Know Your Business) dans votre tableau de bord
Remplacez sk_test_ par votre clé sk_live_
Vérifiez votre callback_url en HTTPS
Configurez vos alertes de solde bas

En production, assurez-vous que votre callback_url retourne un HTTP 200 dans les 10 secondes. En cas d'échec, ElyonPay retente 3 fois avec un délai exponentiel.