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.
https://api.elyonpay.org/apiToutes 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
- Intégration simple — Lien de paiement + iframe, vérification active du statut
- 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, Flutter
Démarrage rapide
Suivez ces 3 étapes pour effectuer votre premier paiement :
- Contactez-nous pour obtenir votre clé API
- Installez le SDK de votre langage ou utilisez cURL directement
- Appelez
POST /api/request-to-pay/payment/linkavec le montant et les URLs de redirection
curl -X POST https://api.elyonpay.org/api/request-to-pay/payment/link \
-H "Authorization: Bearer <your_jwt_token>" \
-H "Content-Type: application/json" \
-H "language: fr" \
-d '{
"amount": 15000,
"user_lang": "fr",
"msisdn": "+237600000000",
"success": "https://yoursite.com/success",
"error": "https://yoursite.com/error"
}'Authentification
L'API ElyonPay utilise l'authentification JWT (JSON Web Token). Obtenez votre token via l'endpoint de login, puis incluez-le dans chaque requête.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| username | string | Requis | Email du compte marchand |
| password | string | Requis | Mot de passe du compte |
| role | string | Requis | ROLE_MERCHANT_ADMIN |
curl -X POST https://api.elyonpay.org/api/login \
-H "Content-Type: application/json" \
-d '{
"username": "you@example.com",
"password": "***",
"role": "ROLE_MERCHANT_ADMIN"
}'Réponse
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...."
}Utilisation dans l'en-tête HTTP
Authorization: Bearer <your_jwt_token>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.net/api | Aucun débit réel — données simulées |
Production | https://api.elyonpay.org/api | Transactions réelles |
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_token_jwt} | Requis |
Content-Type | application/json | Requis (POST) |
Accept | application/json | Optionnel |
Idempotency-Key | UUID unique | Recommandé |
Format de réponse standard
{
"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
Génère un lien de paiement sécurisé. Le client est redirigé vers ce lien pour choisir sa méthode de paiement (Mobile Money, carte bancaire) et finaliser la transaction.
Paramètres du body
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| amount | number | Requis | Montant du paiement |
| user_lang | string | Requis | Langue de l'interface de paiement (fr, en) |
| msisdn | string | Requis | Numéro de téléphone au format international : +237600000000 |
| success | string | Requis | URL de redirection en cas de succès |
| error | string | Requis | URL de redirection en cas d'erreur |
Réponse
{
"url": "https://app.elyonpay.org/t/CI032667e43abf11?success=https://www.success.com&error=https://www.error.com"
}Exemples de code
cURL
curl -X POST https://api.elyonpay.org/api/request-to-pay/payment/link \
-H "Authorization: Bearer <your_jwt_token>" \
-H "Content-Type: application/json" \
-H "language: fr" \
-d '{
"amount": 15000,
"user_lang": "fr",
"msisdn": "+237600000001",
"success": "https://yoursite.com/success",
"error": "https://yoursite.com/error"
}'Node.js / JavaScript
const response = await fetch('https://api.elyonpay.org/api/request-to-pay/payment/link', {
method: 'POST',
headers: {
'Authorization': 'Bearer ' + token,
'Content-Type': 'application/json',
'language': 'fr'
},
body: JSON.stringify({
amount: 15000,
user_lang: 'fr',
msisdn: '+237600000001',
success: 'https://yoursite.com/success',
error: 'https://yoursite.com/error'
})
});
const data = await response.json();
console.log(data.url); // Payment link to redirect the customerPHP
$ch = curl_init('https://api.elyonpay.org/api/request-to-pay/payment/link');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Content-Type: application/json',
'language: fr'
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => 15000,
'user_lang' => 'fr',
'msisdn' => '+237600000001',
'success' => 'https://yoursite.com/success',
'error' => 'https://yoursite.com/error'
])
]);
$response = json_decode(curl_exec($ch), true);
echo $response['url']; // Payment linkTransactions
Récupérez l'historique complet de vos transactions : paiements reçus, remboursements, frais.
Retourne la liste paginée de toutes vos transactions. Vous pouvez également récupérer le détail d'une transaction spécifique via son identifiant.
Détail d'une transaction
curl -X GET https://api.elyonpay.org/api/transactions/1553 \
-H "Authorization: Bearer <your_jwt_token>" \
-H "Accept: application/json"Exemple de réponse
{
"id": 1553,
"PSPid": "FR033169cbd9c1f1",
"uuid": "FR033169cbd9c1f1",
"creation_date": "2026-03-31T14:27:13+00:00",
"validation_date": null,
"delivery_date": null,
"amount": 100,
"totalCustomer": 100,
"state": "CREATED",
"ticket_type": "SMS_EMAIL",
"operation_code": "03",
"payer_phone_number": "+33782112127",
"beneficiary_phone_number": "+33782112127",
"payer_currency": "EUR",
"beneficiary_currency": "EUR",
"payer_country": "FR",
"beneficiary_country": "FR",
"payment": {
"name": "MOLLIE"
},
"customer": {
"phoneNumber": "+33782112127",
"email": "client@example.com"
},
"merchant": {
"id": 258,
"name": "Ma Boutique",
"city": "Paris",
"address": "10 Rue de la Paix",
"zipCode": "75002",
"type": "individual",
"country_code": "FR",
"country": "France"
},
"transactionStates": [
{
"state": "CREATED",
"date": "2026-03-31T14:27:14+00:00"
}
],
"commission_operateur": 0,
"commission_marchand": 0,
"commission_pays": 0,
"commission_customer": 0,
"deliveryPrice": 0
}Champs de la réponse
| Champ | Type | Description |
|---|---|---|
| id | integer | Identifiant interne de la transaction |
| PSPid | string | Identifiant unique ElyonPay (ex : FR033169cbd9c1f1) |
| uuid | string | Identifiant unique — même valeur que PSPid |
| creation_date | datetime | Date de création (ISO 8601 avec timezone) |
| validation_date | datetime|null | Date de validation du paiement — null si non encore validé |
| delivery_date | datetime|null | Date de livraison — null si non applicable |
| amount | number | Montant de la transaction dans la devise du bénéficiaire |
| totalCustomer | number | Montant total facturé au client (commissions incluses) |
| state | string | Statut actuel : CREATED, PENDING, SUCCESSFUL, FAILED, EXPIRED |
| ticket_type | string | Type de notification : SMS_EMAIL, SMS, EMAIL |
| operation_code | string | Code d'opération interne |
| payer_phone_number | string | Numéro de téléphone du payeur (format international) |
| beneficiary_phone_number | string | Numéro de téléphone du bénéficiaire |
| payer_currency | string | Devise du payeur (code ISO 4217 : EUR, XAF, XOF...) |
| beneficiary_currency | string | Devise du bénéficiaire |
| payer_country | string | Code pays du payeur (ISO 3166 : FR, CM, CI...) |
| beneficiary_country | string | Code pays du bénéficiaire |
| payment.name | string | Fournisseur de paiement utilisé (MOLLIE, MTN, ORANGE...) |
Objet customer
| Champ | Type | Description |
|---|---|---|
| phoneNumber | string | Numéro de téléphone du client |
| string | Adresse email du client |
Objet merchant
| Champ | Type | Description |
|---|---|---|
| id | integer | Identifiant du marchand |
| name | string | Nom du marchand ou de l'enseigne |
| city | string | Ville du marchand |
| address | string | Adresse postale |
| zipCode | string | Code postal |
| type | string | Type de compte : individual, company |
| country_code | string | Code pays ISO 3166 (FR, CM, CI...) |
| country | string | Nom du pays |
Tableau transactionStates
Historique des changements de statut de la transaction, du plus ancien au plus récent.
| Champ | Type | Description |
|---|---|---|
| state | string | Statut à cet instant (CREATED, PENDING, SUCCESSFUL, FAILED...) |
| date | datetime | Date du changement de statut |
Commissions
| Champ | Type | Description |
|---|---|---|
| commission_operateur | number | Commission opérateur télécom |
| commission_marchand | number | Commission marchand |
| commission_pays | number | Commission pays |
| commission_customer | number | Commission appliquée au client |
| deliveryPrice | number | Frais de livraison |
SDKs officiels
Des SDKs officiels sont disponibles pour les principaux langages et frameworks. Ils gèrent automatiquement l'authentification et les erreurs.
Flux d'intégration
ElyonPay utilise un modèle en 6 étapes basé sur un lien de paiement et une vérification active du statut (modèle pull). Aucune infrastructure webhook n'est nécessaire.
Obtenir un lien de paiement
Votre backend appelle POST /api/request-to-pay/payment/link avec le montant et les URLs de redirection (success / error). L'API retourne une URL de paiement unique.
Afficher l'iframe de paiement
Redirigez le client vers l'URL retournée, ou intégrez-la dans une iframe. Le client choisit sa méthode de paiement (Mobile Money, carte bancaire) et saisit ses informations.
Validation du paiement
Le client confirme le paiement côté opérateur (code USSD Mobile Money, 3D Secure carte). ElyonPay traite la transaction.
Redirection vers votre backend
Une fois le paiement traité, le client est redirigé vers votre URL success ou error selon le résultat. L'UUID de la transaction est transmis dans l'URL de redirection.
Vérifier le statut de la transaction
Votre backend appelle GET /api/transactions/{uuid} pour récupérer le statut définitif de la transaction. Cette vérification côté serveur est indispensable — ne vous fiez jamais uniquement à l'URL de redirection.
Afficher la confirmation au client
Selon le statut retourné (SUCCESSFUL, FAILED, EXPIRED...), affichez la page de confirmation ou d'erreur appropriée à votre client.
Diagramme — Initiation du paiement
sequenceDiagram
participant Customer
participant Merchant
participant ElyonPay
Customer->>Merchant: Finalizes cart
Customer->>Merchant: Selects "Pay"
Merchant->>ElyonPay: POST /api/login
ElyonPay-->>Merchant: Returns JWT token
Merchant->>ElyonPay: POST /api/request-to-pay/payment/link
ElyonPay-->>Merchant: Returns payment URL
Merchant->>Customer: Displays payment page (iframe or redirect)
Customer->>ElyonPay: Selects payment method
Customer->>ElyonPay: Completes transaction
ElyonPay-->>Customer: Shows confirmation popup
Diagramme — Résultat du paiement
sequenceDiagram
participant Customer
participant Merchant
participant ElyonPay
Customer->>ElyonPay: Transaction completed
alt Successful payment
ElyonPay->>Merchant: Redirect to success URL
else Failed payment
ElyonPay->>Merchant: Redirect to error URL
end
Merchant->>ElyonPay: GET /api/transactions/[ID_TRANSACTION]
ElyonPay-->>Merchant: Returns transaction status
Merchant->>Merchant: Updates order status
Merchant->>Customer: Shows order confirmation
Exemple d'implémentation (étapes 1 → 5)
Node.js / Express
// 1. Create payment link
app.post('/checkout', async (req, res) => {
const response = await fetch('https://api.elyonpay.org/api/request-to-pay/payment/link', {
method: 'POST',
headers: {
'Authorization': 'Bearer ' + token,
'Content-Type': 'application/json',
'language': 'fr'
},
body: JSON.stringify({
amount: req.body.amount,
user_lang: 'fr',
msisdn: req.body.phone,
success: 'https://yoursite.com/payment/done',
error: 'https://yoursite.com/payment/error'
})
});
const { url } = await response.json();
res.redirect(url); // 2. Redirect customer to payment page
});
// 4 → 5. Handle redirect & verify status
app.get('/payment/done', async (req, res) => {
// The transaction uuid is available from your order context
const tx = await fetch(`https://api.elyonpay.org/api/transactions/${uuid}`, {
headers: { 'Authorization': 'Bearer ' + token }
}).then(r => r.json());
if (tx.state === 'SUCCESSFUL') {
// 6. Show confirmation
res.render('success', { transaction: tx });
} else {
res.render('pending', { transaction: tx });
}
});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 |
Couverture : Cameroun, Nigeria, Côte d'Ivoire, Ghana, Ouganda, Sénégal, Mali, Burkina Faso, Bénin, Togo, Niger, Kenya, Tanzanie, Zambie, République Démocratique du Congo.
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.
Diagramme des transitions d'état
stateDiagram-v2
[*] --> CREATED
CREATED --> PENDING: Payment initiated
PENDING --> WAITING_FOR_PAYMENT: Awaiting customer
WAITING_FOR_PAYMENT --> ACCEPTED: Payment confirmed
PENDING --> ACCEPTED: Direct approval
PENDING --> REJECTED: Validation failed
PENDING --> DECLINED: Payment issue
WAITING_FOR_PAYMENT --> DECLINED: Payment issue
WAITING_FOR_PAYMENT --> CANCELLED: User cancellation
ACCEPTED --> DELIVERED: Funds transferred
ACCEPTED --> CANCELLED: Administrative action
REJECTED --> [*]
DECLINED --> [*]
CANCELLED --> [*]
DELIVERED --> [*]
Codes d'erreur
En cas d'erreur, l'API retourne un objet JSON avec un code d'erreur machine et un message lisible.
{
"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 EUR | Carte (Visa, Mastercard), PayPal |
USD | Dollar américain | 0,50 USD | Carte, PayPal |
GBP | Livre sterling | 0,30 GBP | 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. Connectez-vous sur api.elyonpay.net — aucun débit réel ne sera effectué.
Comptes de test par pays
Utilisez ces identifiants pour tester l'intégration sur l'environnement sandbox. Chaque compte est associé à un pays et une devise spécifiques.
| Téléphone | Mot de passe | |
|---|---|---|
+237683191284 | demo+23733@elyonpay.com | CompteDemo1 |
| Téléphone | Mot de passe | |
|---|---|---|
+2250758789285 | demo+225@elyonpay.com | CompteDemo1 |
| Téléphone | Mot de passe | |
|---|---|---|
+33895555555 | demo+33@elyonpay.com | CompteDemo1 |
Limites du sandbox
- Les transactions sandbox n'engendrent aucuns frais
- 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
- Changez l'URL de base de
api.elyonpay.netversapi.elyonpay.org - Vérifiez votre
callback_urlen HTTPS - Configurez vos alertes de solde bas
