N
nelsiuspay
/docs

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.

REST v1.0

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.

Base URL Universelle

Tous les endpoints de l'API NelsiusPay (Production et Sandbox) partagent le même point d'entrée sécurisé :

https://api.nelsiuspay.com/api/v1

Le basculement entre Sandbox et Live s'effectue uniquement via votre clé API (sk_test_... vs sk_live_...).

curl -X GET "https://api.nelsiuspay.com/api/v1/payments/COMMANDE_99812" \
  -H "X-Api-Key: sk_test_votre_cle_privee" \
  -H "Accept: application/json"

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

Content-Type: application/json
Accept: application/json
X-Api-Key: sk_test_votre_cle_privee
curl -X GET "https://api.nelsiuspay.com/api/v1/payments/COMMANDE_99812" \
  -H "X-Api-Key: sk_test_votre_cle_privee" \
  -H "Accept: application/json"
SDK V2

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
v2.0.0

Typescript natif, ESM & CommonJS, gestionnaire de webhooks Express / Fastify / Next.js.

npm install nelsius-pay
Dépôt GitHubnpm: nelsius-pay
PHP SDK (PSR-4 / Guzzle)
v2.0.0

PHP 8.0+, compatible Vanilla PHP, Symfony, WordPress, PrestaShop et frameworks modernes.

composer require nelsius/nelsius-pay-php
Dépôt GitHubpackagist: nelsius-pay-php
Python (Django / Flask / FastAPI)
v2.0.0

Python 3.8+, requêtes optimisées, validation de signature HMAC, support asynchrone et synchrone.

pip install nelsius-pay
Dépôt GitHubpypi: nelsius-pay
Laravel Package (Auto-Discovery)
v2.0.0

Service Provider, Facade Nelsius::checkout(), fichier de config nelsius.php et variables .env.

composer require nelsius/nelsius-pay-laravel
Dépôt GitHubLaravel 9, 10, 11+
Installation directe depuis GitHub

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
# Utilisation directe REST sans SDK
curl -X POST "https://api.nelsiuspay.com/api/v1/checkout/initiate" \
  -H "Authorization: Bearer sk_live_votre_cle_secrete" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "customer_name": "Jean Dupont",
    "customer_email": "jean@example.com",
    "customer_phone": "+237699112233",
    "default_country": "CM",
    "allowed_countries": ["CM", "CI", "SN"],
    "return_url": "https://monsite.com/commande/succes",
    "cancel_url": "https://monsite.com/commande/annule",
    "description": "Paiement commande #CMD-8493"
  }'
MULTI-APP

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.

1. Clés API Dédiées

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.

2. Webhooks 100% Étanches

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.

3. Comptabilité & Stats Isolées

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.
Identification dans l'objet Metadata

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.

curl -X POST "https://api.nelsiuspay.com/api/v1/checkout/initiate" \
  -H "X-Api-Key: sk_live_app_vtc_89a1f290d812..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "XAF",
    "reference": "CMD_TAXI_99812",
    "metadata": {
      "app_id": "app_live_vtc_mobile",
      "app_name": "Application Taxi VTC"
    }
  }'
GET/public/payment-configConfig

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.

Architecture Multi-Partenaires Extensible

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.

Couverture des autres pays non listés (Monde entier)

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

PaysCode ISOIndicatifDeviseOpérateurs Disponibles & Codes
🇧🇯BéninBJ+229XOF
MTN Mobile MoneyMTN_MOMO_BENMoov MoneyMOOV_BEN
🇨🇲CamerounCM+237XAF
MTN MoMoMTN_MOMO_CMROrange MoneyORANGE_CMR
🇨🇬Congo-BrazzavilleCG+242XAF
MTN MoMoMTN_MOMO_COGAirtel MoneyAIRTEL_COG
🇨🇮Côte d'IvoireCI+225XOF
WaveWAVE_CIVOrange MoneyORANGE_CIVMTN MoMoMTN_MOMO_CIVMoov MoneyMOOV_CIV
🇨🇩RDC (Congo Kinshasa)CD+243CDF / USD
Vodacom M-PesaVODACOM_CODAirtel MoneyAIRTEL_CODOrange MoneyORANGE_CODAfricellAFRICELL_COD
🇬🇭GhanaGH+233GHS
MTN MoMoMTN_MOMO_GHAVodafone CashVODAFONE_GHAAirtelTigoAIRTELTIGO_GHA
🇰🇪KenyaKE+254KES
Safaricom M-PesaMPESA_KENAirtel MoneyAIRTEL_KEN
🇱🇷LibériaLR+231LRD / USD
Lonestar MTN MoMoMTN_MOMO_LBR
🇲🇼MalawiMW+265MWK
Airtel MoneyAIRTEL_MWITNM MpambaTNM_MWI
🇲🇿MozambiqueMZ+258MZN
M-PesaMPESA_MOZVodacomVODACOM_MOZE-MolaEMNOLA_MOZ
🇳🇬NigériaNG+234NGN
MTN MoMo PSBMTN_MOMO_NGAAirtel SmartcashAIRTEL_NGA
🇷🇼RwandaRW+250RWF
MTN MoMo RwandaMTN_MOMO_RWAAirtel MoneyAIRTEL_RWA
🇸🇳SénégalSN+221XOF
WaveWAVE_SENOrange MoneyORANGE_SENFree MoneyFREE_SENExpressoEXPRESSO_SEN
🇸🇱Sierra LeoneSL+232SLE
Orange MoneyORANGE_SLEAfrimoneyAFRIMONEY_SLE
🇹🇿TanzanieTZ+255TZS
M-Pesa VodacomVODACOM_TZAAirtel MoneyAIRTEL_TZATigo PesaTIGO_TZAHaloPesaHALOPESA_TZA
🇺🇬OugandaUG+256UGX
MTN MoMoMTN_MOMO_UGAAirtel MoneyAIRTEL_UGA
🇿🇲ZambieZM+260ZMW
MTN MoMoMTN_MOMO_ZMBAirtel MoneyAIRTEL_ZMBZamtel KwachaZAMTEL_ZMB

Filtrer par pays spécifique (`GET /public/payment-operators`)

Pour récupérer uniquement les opérateurs d'un pays donné, vous pouvez appeler :

GET https://api.nelsiuspay.com/api/v1/public/payment-operators?country=CM
curl -X GET "https://api.nelsiuspay.com/api/v1/public/payment-config" \
  -H "Accept: application/json"
Sandbox Isolé

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 TestNuméro Mobile MoneyRésultat Webhook
Succès ImmédiatFinit par 000 (ex: +237690000000)Statut completed + dispatch payment.success
Échec ImmédiatFinit 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 :

{ "reference": "CHK_98A01948B", "action": "success" }
curl -X POST "https://api.nelsiuspay.com/api/v1/sandbox/simulate" \
  -H "X-Api-Key: sk_test_votre_cle_privee" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reference": "CHK_98A01948B",
    "action": "success"
  }'
POST/checkout/initiateHébergé

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)

ChampObligatoireDescription
amountOuiMontant demandé (ex: 5000).
currencyNonDevise ISO 4217 (ex: XAF, EUR, USD, XOF). Par défaut XAF.
fee_bearerNonQui paie les frais : "customer" (client en sus) ou "merchant" (vendeur absorbe). Voir section dédiée ci-dessous.
referenceNonVotre identifiant de commande unique (ex: CMD_99812).
default_countryNonCode 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_countriesNonTableau de pays autorisés pour restreindre le checkout (ex: ["CM", "CI", "SN"]). Si omis, tous vos pays et passerelles actifs s'affichent.
customer_nameNonNom et prénom du client pour pré-remplir la facture et l'interface de paiement.
customer_emailNonAdresse e-mail du payeur pour l'envoi automatique du reçu et des OTP.
customer_phoneNonNuméro de téléphone au format local ou international (ex: "+237699112233").
descriptionNonIntitulé ou motif du paiement visible par l'acheteur sur la page de caisse.
return_urlNonURL de redirection automatique du navigateur après validation du paiement.
payment_methodsNonTableau pour restreindre les options (ex: ["orange_money", "mtn_money"], ["card"], ou ["paypal"]). Si omis, toutes vos passerelles actives s'affichent.
curl -X POST "https://api.nelsiuspay.com/api/v1/checkout/initiate" \
  -H "X-Api-Key: sk_test_votre_cle_privee" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "fee_bearer": "customer",
    "customer_name": "Jean Dupont",
    "customer_email": "client@example.com",
    "customer_phone": "+237670000000",
    "default_country": "CM",
    "allowed_countries": ["CM", "CI", "SN"],
    "description": "Abonnement Pro Mensuel",
    "reference": "COMMANDE_99812",
    "return_url": "https://monsite.com/commande/succes",
    "cancel_url": "https://monsite.com/commande/annule",
    "metadata": {
      "order_id": "CMD-99812"
    }
  }'
POST/payments/chargePush USSD

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.

Fonctionnement & Éligibilité DirectPay
  • 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/charge ou POST /api/v1/directpay/initiate.

Cycle de vie d'un paiement DirectPay (3 Étapes)

Étape 1 • Appel API

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".

Étape 2 • Push USSD

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.

Étape 3 • Webhook

Dès confirmation, NelsiusPay envoie l'événement payment.success signé sur votre serveur.

curl -X POST "https://api.nelsiuspay.com/api/v1/payments/charge" \
  -H "X-Api-Key: sk_test_votre_cle_privee" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "amount": 2500,
    "currency": "XAF",
    "operator": "MTN_MOMO_CMR",
    "phone": "+237670000000",
    "reference": "DIRECT_PAY_55410",
    "customer": {
      "name": "Jean Dupont",
      "email": "jean.dupont@example.com"
    },
    "metadata": {
      "custom_user_id": "usr_99182"
    }
  }'
Politique Frais

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 :

1. "merchant" (Par défaut)

Le vendeur absorbe les frais de transaction.

Client paie : 10 000 XAF
Frais (2.5%) : 250 XAF
Net crédité : 9 750 XAF
2. "customer" (Client en sus)

Les frais sont ajoutés à la facture du client.

Client paie : 10 250 XAF
Frais ajoutés : 250 XAF
Net crédité : 10 000 XAF (100%)
3. "split" (Partagé 50/50)

Les frais sont divisés également entre acheteur et vendeur.

Client paie : 10 125 XAF
Part client : 125 XAF
Net crédité : 9 875 XAF

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.

Montant initial10 000 XAF
Frais estimés (2.5%)250 XAF
Débité au client10 250 XAF
Net dans votre Wallet10 000 XAF
Corps JSON envoyé à l'API :
{
  "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.

curl -X GET "https://api.nelsiuspay.com/api/v1/pay/estimate-fees?amount=10000&currency=XAF&operator=MTN_MOMO_CMR&fee_bearer=customer" \
  -H "X-Api-Key: sk_test_votre_cle_privee" \
  -H "Accept: application/json"
GET/payments/{reference}Statut

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

pendingEn attente de confirmation ou de saisie du PIN.
completedPaiement certifié. Les fonds sont disponibles dans votre wallet.
failedTransaction annulée, expirée ou solde insuffisant.
curl -X GET "https://api.nelsiuspay.com/api/v1/payments/COMMANDE_99812" \
  -H "X-Api-Key: sk_test_votre_cle_privee" \
  -H "Accept: application/json"
POST/votre-webhook-urlNotification

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.

// En PHP :
$hash = hash_hmac('sha256', $rawPayload, $webhookSecret);
// En Node.js :
crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
// Payload JSON reçu lors d'un webhook NelsiusPay :
{
  "event": "payment.success",
  "data": {
    "transaction_code": "CHK_98A01948B",
    "reference": "COMMANDE_99812",
    "amount": 5000,
    "fee": 125,
    "net_amount": 4875,
    "fee_bearer": "merchant",
    "currency": "XAF",
    "status": "completed",
    "operator": "MTN_MOMO_CMR",
    "customer": {
      "phone": "+237670000000",
      "email": "client@example.com"
    },
    "metadata": {
      "order_id": "CMD-99812"
    }
  }
}
Standard MCP

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.

Configuration Claude Desktop / Cursor
{
  "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.

200 / 201 • Succès

Requête traitée ou ressource créée avec succès.

400 / 422 • Données Invalides

Corps JSON manquant ou numéro de téléphone malformé.

401 • Non Autorisé

Clé API invalide, absente ou révoquée dans l'en-tête.

403 • Entreprise Requise

DirectPay en Live réservé aux entreprises vérifiées.

curl -X GET "https://api.nelsiuspay.com/api/v1/payments/COMMANDE_99812" \
  -H "X-Api-Key: sk_test_votre_cle_privee" \
  -H "Accept: application/json"
© 2026 NelsiusPay Technologies • Spécifications d'Intégration Développeur.
Documentation API Développeur & Intégration | NelsiusPay