Guide de Démarrage
Introduction
Ce que représente l'API NelsiusPay, les clés d'environnement, et comment orchestrer vos flux de paiement Mobile Money, cartes et cryptomonnaies.
Documentation API Développeur NelsiusPay
Spécifications techniques REST unifiées pour orchestrer les paiements Mobile Money (17 pays en Afrique), cartes bancaires internationales, PayPal mondial et cryptomonnaies.
L'API Développeur NelsiusPay connecte votre application aux réseaux de paiement locaux africains et internationaux. Grâce à notre infrastructure dynamique multi-partenaires (agrégation GeniusPay, MamoniPay, PayPal, Stripe), chaque nouveau partenaire ou opérateur activé est instantanément mis à disposition des marchands sans nécessiter de refactorisation de code.
Tous les endpoints de l'API NelsiusPay (Production et Sandbox) partagent le même point d'entrée sécurisé :
Le basculement entre Sandbox et Live s'effectue uniquement via votre clé API (sk_test_... vs sk_live_...).
Authentification & Gestion des Clés
Toutes les requêtes marchands sont sécurisées par votre clé secrète transmise dans l'en-tête HTTP X-Api-Key ou Authorization.
NelsiusPay utilise un système de clés compartimenté :
- Clé Secrète Test (
sk_test_...) :Permet de tester tous les endpoints dans un bac à sable isolé sans argent réel et sans vérification d'entreprise obligatoire. - Clé Secrète Live (
sk_live_...) :Traite les flux financiers réels. Ne la partagez jamais côté client (front-end). - Clé Publique (
pk_live_...) :Utilisée pour initialiser nos SDKs mobiles ou formulaires intégrés.
En-têtes HTTP Requis
SDKs Officiels & Librairies Développeur (V2)
Intégrez NelsiusPay dans votre langage de prédilection en quelques secondes grâce à nos packages officiels pré-compilés et optimisés.
Pour faciliter l'intégration dans vos projets sans écrire manuellement des requêtes HTTP brutes, nous maintenons des bibliothèques open-source officielles avec typage strict, gestion des exceptions, validation des webhooks HMAC et sélection automatique des réseaux.
Node.js & TypeScript
Typescript natif, ESM & CommonJS, gestionnaire de webhooks Express / Fastify / Next.js.
PHP SDK (PSR-4 / Guzzle)
PHP 8.0+, compatible Vanilla PHP, Symfony, WordPress, PrestaShop et frameworks modernes.
Python (Django / Flask / FastAPI)
Python 3.8+, requêtes optimisées, validation de signature HMAC, support asynchrone et synchrone.
Laravel Package (Auto-Discovery)
Service Provider, Facade Nelsius::checkout(), fichier de config nelsius.php et variables .env.
Si vous souhaitez tester directement la dernière version sans attendre la mise à jour des registres publics :
- Node.js :
npm install github:nelson-siebi/nelsius-pay-node#v2.0.0 - Python :
pip install git+https://github.com/nelson-siebi/nelsius-pay-python.git@v2.0.0
Multi-Applications & Isolation des Projets
Compartimentez vos encaissements, clés API et webhooks pour connecter plusieurs applications (mobile, e-commerce, SaaS) sur un compte unique sans collision de webhooks ni mélange de chiffre d'affaires.
Si vous développez plusieurs produits (ex : une application mobile de transport, un site e-commerce et un logiciel SaaS), NelsiusPay vous permet de créer des Applications distinctes dans votre tableau de bord sans avoir à ouvrir plusieurs comptes marchands.
Chaque application possède sa propre clé secrète (sk_live_...). Révoquer ou régénérer la clé d'une application n'impacte jamais vos autres projets.
Quand un paiement est initié pour l'App Mobile, le webhook est envoyé uniquement à l'URL configurée pour cette application. Vos autres applications ne reçoivent aucune notification parasite.
Dans le tableau de bord, vous filtrez les graphiques, le volume et le taux de succès pour chaque application en un clic, ou consultez la vue consolidée globale.
Comment se passent les Retraits de fonds (Cashout & Payouts) ?
La gestion des retraits de vos gains s'effectue de deux façons selon votre cas d'usage :
- Retrait Manuel depuis le Tableau de Bord : Les revenus nets collectés par l'ensemble de vos applications sont crédités sur vos portefeuilles multidevises sécurisés (XAF, XOF, EUR, USD). Vous pouvez consulter la part exacte de chiffre d'affaires générée par chaque application, puis demander un virement vers vos comptes Mobile Money (Orange Money, MTN MoMo, Wave) ou votre compte bancaire / RIB. Chaque retrait est protégé par votre Code PIN de transaction et une validation OTP par email.
- Reversements Programmatiques (API Payouts) : Si vous gérez une marketplace ou une application mobile avec des reversements automatiques (ex : paiement des chauffeurs ou des vendeurs partenaires), notre endpoint de déboursement débite votre solde disponible et crédite instantanément le compte Mobile Money du bénéficiaire.
Vous pouvez passer un identifiant personnalisé dans chaque requête via metadata.app_id. Cet objet vous est retourné tel quel dans le webhook de notification, facilitant l'aiguillage dans votre architecture microservices.
Pays Supportés & Route Dynamique
Interrogez dynamiquement la liste temps réel des pays, devises et opérateurs actifs pour alimenter vos formulaires et checkout personnalisés.
Pour éviter d'avoir à coder en dur des listes d'opérateurs qui évoluent, NelsiusPay met à disposition un endpoint public mis en cache haute performance : GET /api/v1/public/payment-config.
Cet endpoint renvoie la liste filtrée des pays ayant au moins un opérateur actif en temps réel, évitant ainsi de proposer à vos clients des moyens momentanément indisponibles.
NelsiusPay fonctionne comme un routeur financier intelligent. Lorsqu'un nouveau partenaire de paiement (ex: nouvel agrégateur bancaire, nouveau réseau local) est ajouté par l'administrateur, il apparaît instantanément dans la réponse de cette route sans nécessiter de mise à jour de vos SDKs ou applications.
Pour tous les pays non couverts par un opérateur Mobile Money local africain (Europe, États-Unis, Canada, Asie, Moyen-Orient, Amérique Latine, etc.), vos clients internationaux peuvent payer immédiatement via :
- PayPal Wallet & Solde : Accessible dans plus de 200 pays et territoires en devises majeures (EUR, USD, GBP, CAD...).
- Cartes Bancaires Visa & Mastercard : Acceptation mondiale sécurisée avec 3D-Secure automatique.
- Cryptomonnaies (USDT) : Règlements universels instantanés sans aucune barrière territoriale.
Matrice Complète des 17 Pays Africains & Opérateurs
Filtrer par pays spécifique (`GET /public/payment-operators`)
Pour récupérer uniquement les opérateurs d'un pays donné, vous pouvez appeler :
Mode Sandbox & Simulation Immédiate
Testez et validez la totalité de vos parcours d'achat sans compte bancaire réel ni documents légaux.
Pour activer le mode Sandbox, utilisez simplement votre clé sk_test_.... Les requêtes s'exécutent sur la même URL mais ne débitent aucun compte.
Jeux de Numéros de Test
| Scénario Test | Numéro Mobile Money | Résultat Webhook |
|---|---|---|
| Succès Immédiat | Finit par 000 (ex: +237690000000) | Statut completed + dispatch payment.success |
| Échec Immédiat | Finit par 111 (ex: +237691111111) | Statut failed + dispatch payment.failed |
| En Attente (Simulation) | Tout autre numéro (ex: +237675123456) | Reste à l'état pending pour simulation manuelle via l'API ci-dessous. |
Simuler manuellement par API
Pour valider ou échouer à la demande une transaction pending, appelez POST /api/v1/sandbox/simulate avec le corps :
Checkout Hébergé (Hosted Checkout)
Créez une session de paiement complète et redirigez le client vers notre portail optimisé (Mobile Money, Carte, PayPal, QR Code).
Le Checkout Hébergé est la méthode recommandée pour 90% des applications. Il prend en charge l'affichage adaptatif selon le pays de l'acheteur, les rappels par SMS et l'évaluation en temps réel.
Paramètres de la requête (JSON)
| Champ | Obligatoire | Description |
|---|---|---|
| amount | Oui | Montant demandé (ex: 5000). |
| currency | Non | Devise ISO 4217 (ex: XAF, EUR, USD, XOF). Par défaut XAF. |
| fee_bearer | Non | Qui paie les frais : "customer" (client en sus) ou "merchant" (vendeur absorbe). Voir section dédiée ci-dessous. |
| reference | Non | Votre identifiant de commande unique (ex: CMD_99812). |
| default_country | Non | Code ISO à 2 lettres du pays pré-sélectionné lors de l'arrivée du client (ex: "CM" pour Cameroun, "CI" pour Côte d'Ivoire, "SN" pour Sénégal). Par défaut "CM". |
| allowed_countries | Non | Tableau de pays autorisés pour restreindre le checkout (ex: ["CM", "CI", "SN"]). Si omis, tous vos pays et passerelles actifs s'affichent. |
| customer_name | Non | Nom et prénom du client pour pré-remplir la facture et l'interface de paiement. |
| customer_email | Non | Adresse e-mail du payeur pour l'envoi automatique du reçu et des OTP. |
| customer_phone | Non | Numéro de téléphone au format local ou international (ex: "+237699112233"). |
| description | Non | Intitulé ou motif du paiement visible par l'acheteur sur la page de caisse. |
| return_url | Non | URL de redirection automatique du navigateur après validation du paiement. |
| payment_methods | Non | Tableau pour restreindre les options (ex: ["orange_money", "mtn_money"], ["card"], ou ["paypal"]). Si omis, toutes vos passerelles actives s'affichent. |
Paiement Direct (DirectPay Server-to-Server)
Déclenchez directement un débit Mobile Money (Push USSD sans redirection) ou une passerelle carte directe de serveur à serveur.
- En mode Sandbox : DirectPay est immédiatement disponible sans restriction avec vos clés
sk_test_...pour prototyper et automatiser vos tests. - En mode Live (Production) : Pour des raisons de conformité anti-fraude des opérateurs télécoms, le débit direct Server-to-Server est réservé aux entreprises certifiées (KYC Entreprise validé, RCCM / NIF renseigné). Pour les particuliers, utilisez le Checkout Hébergé.
- Alias supporté : Vous pouvez appeler indifféremment
POST /api/v1/payments/chargeouPOST /api/v1/directpay/initiate.
Cycle de vie d'un paiement DirectPay (3 Étapes)
Votre serveur envoie le montant, le numéro de téléphone et le code opérateur. L'API répond immédiatement status: "pending".
L'opérateur télécom déclenche un prompt USSD sur le téléphone du client : il tape son code PIN secret pour autoriser le débit.
Dès confirmation, NelsiusPay envoie l'événement payment.success signé sur votre serveur.
Configuration des Frais Marchand (Fee Bearer)
Personnalisez la prise en charge des commissions de passerelle : laissez le client payer en sus ou absorbez-les pour afficher un tarif net transparent.
NelsiusPay vous offre un contrôle total sur l'attribution des frais grâce au paramètre fee_bearer (porteur des frais), configurable au niveau de votre compte ou surchargeable à chaque requête API :
Le vendeur absorbe les frais de transaction.
Les frais sont ajoutés à la facture du client.
Les frais sont divisés également entre acheteur et vendeur.
Simulateur Interactif de Frais & Requête API
Testez vos paramètres ci-dessous : la simulation calcule le montant net et génère la charge JSON en direct.
{
"amount": 10000,
"currency": "XAF",
"operator": "MTN_MOMO_CMR",
"fee_bearer": "customer",
"phone": "+237670000000",
"reference": "CMD_567002",
"customer": {
"name": "Client Test",
"email": "client@example.com"
},
"metadata": {
"source": "api_doc_interactive_tester"
}
}Endpoint d'estimation préalable des frais
Pour afficher les frais sur votre propre page panier avant même que l'utilisateur ne valide, appelez GET /api/v1/pay/estimate-fees avec les paramètres de requête correspondants.
Vérification de Statut en Temps Réel
Interrogez le statut certifié d'un paiement à tout moment à partir du transaction_code Nelsius ou de votre référence commande.
Cet appel serveur à serveur vous permet de sécuriser vos validations de commande même en cas de fermeture du navigateur par le client.
États possibles de la transaction
Webhooks & Sécurité de Signature HMAC
Recevez des notifications asynchrones instantanées dès qu'un paiement est validé ou rejeté par les opérateurs.
Pour être notifié en temps réel, renseignez votre URL de Webhook dans Dashboard > Paramètres > Webhooks.
Vérification de la Signature Cryptographique
Chaque requête envoyée par NelsiusPay inclut l'en-tête HTTP X-Nelsius-Signature. Il s'agit du hachage HMAC-SHA256 du corps brut JSON signé avec votre clé secrète de webhook.
Serveur MCP NelsiusPay (Model Context Protocol)
Intégrez directement l'API NelsiusPay dans vos assistants de code (Claude Desktop, Cursor IDE, Antigravity) grâce au protocole standardisé MCP.
Le Serveur MCP NelsiusPay permet à votre assistant IA de manipuler votre compte marchand en langage naturel, de générer des liens de paiement, de vérifier l'état des règlements et de simuler des paiements en mode Sandbox sans quitter votre éditeur.
{
"mcpServers": {
"nelsiuspay": {
"command": "npx",
"args": ["-y", "@nelsiuspay/mcp-server@latest"],
"env": {
"NELSIUS_API_KEY": "sk_live_votre_cle_ici"
}
}
}
}Codes de Statut HTTP Standardisés
L'API NelsiusPay respecte les codes d'état HTTP conventionnels pour signaler la réussite ou l'échec des requêtes.
Requête traitée ou ressource créée avec succès.
Corps JSON manquant ou numéro de téléphone malformé.
Clé API invalide, absente ou révoquée dans l'en-tête.
DirectPay en Live réservé aux entreprises vérifiées.