Solution de Paiement Mobile, Carte Bancaire & PayPal

Documentation API Développeur Nelsius

v1.0

Spécifications techniques REST pour l'intégration des fonctionnalités de paiement hébergé (Checkout), de paiement direct et de suivi des transactions.

L'API Développeur Nelsius permet d'intégrer des paiements Mobile Money et cartes bancaires directement dans vos plateformes e-commerce, applications web et mobiles.

Base URL (Local / Production)

http://localhost:8000/api/v1

curl -X GET "http://localhost:8000/api/v1/payments/COMMANDE_99812" \
  -H "X-Api-Key: sk_test_your_key_here" \
  -H "Accept: application/json"

Authentification & Clés API

Chaque requête vers l'API nécessite l'en-tête X-Api-Key ou Authorization avec votre clé API marchand.

Nelsius prend en charge les types de clés suivants :

Clé Secrète Sandbox (sk_test_...) : Utilisée en mode test pour simuler les paiements.
Clé Secrète Live (sk_live_...) : Utilisée en production pour traiter de vrais paiements.
Clé Publique (pk_live_...) : Initialisation côté client.

En-têtes HTTP requis

Content-Type: application/json
Accept: application/json
X-Api-Key: sk_test_votre_cle_secrete

curl -X GET "http://localhost:8000/api/v1/payments/COMMANDE_99812" \
  -H "X-Api-Key: sk_test_your_key_here" \
  -H "Accept: application/json"

Initialiser un Checkout Hébergé

POST /checkout/initiate

Génère une session de paiement sécurisée Nelsius et renvoie une URL vers laquelle rediriger le client.

Cette méthode crée une session unique avec une référence marchand et renvoie l'URL de l'interface de paiement.

Paramètres de requête (JSON Body)

Paramètre	Requis	Description
amount	Oui	Montant total de la commande (ex: 5000).
currency	Oui	Code ISO 4217 de la devise (ex: XAF, XOF, USD).
customer_email	Optionnel	Adresse email du client pour l'envoi du reçu.
customer_phone	Optionnel	Numéro de téléphone avec indicatif (ex: +237670000000).
reference	Optionnel	Identifiant unique de votre commande backend.
return_url	Optionnel	URL de retour après paiement validé.
cancel_url	Optionnel	URL d'annulation après clic du client sur annuler.

curl -X POST "http://localhost:8000/api/v1/checkout/initiate" \
  -H "X-Api-Key: sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "customer_email": "client@example.com",
    "customer_phone": "+237670000000",
    "reference": "COMMANDE_99812",
    "return_url": "http://localhost:3000/callback/success",
    "cancel_url": "http://localhost:3000/callback/cancel",
    "metadata": {
      "product_name": "Licence logicielle"
    }
  }'

Paiement Direct (Server-to-Server)

POST /payments/charge

Déclenche directement une demande de débit (Push USSD Mobile Money) sans passer par l'interface hébergée.

Réservé aux marchands certifiés ayant soumis les documents légaux d'entreprise (RCCM, NIF/Tax ID).

Opérateurs supportés (`operator`)

Cameroun : MTN_MOMO_CMR, ORANGE_CMR
Côte d'Ivoire : MTN_MOMO_CIV, ORANGE_CIV, WAVE_CIV, MOOV_CIV
Sénégal : ORANGE_SEN, WAVE_SEN, FREE_SEN
Bénin : MTN_MOMO_BEN, MOOV_BEN

curl -X POST "http://localhost:8000/api/v1/payments/charge" \
  -H "X-Api-Key: sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "amount": 1000,
    "currency": "XAF",
    "phone": "+237670000000",
    "operator": "MTN_MOMO_CMR",
    "reference": "PAY_88123",
    "email": "client@example.com"
  }'

Vérification du Statut d'une Transaction

GET /payments/{reference}

Permet d'interroger l'état d'un paiement à partir du transaction_code ou de la référence marchand.

Cet appel serveur à serveur vous permet de certifier à 100% l'état d'un paiement sans dépendre uniquement de la redirection du navigateur.

Statuts possibles

pendingTransaction en attente de saisie du code PIN par le client.

completedPaiement certifié et solde crédité sur le compte marchand.

failedTransaction rejetée ou solde insuffisant.

curl -X GET "http://localhost:8000/api/v1/payments/COMMANDE_99812" \
  -H "X-Api-Key: sk_test_your_key_here" \
  -H "Accept: application/json"

Webhooks & Notifications Server-to-Server

Réception d'événements asynchrones JSON sur le serveur du marchand.

Pour configurer des notifications automatisées, ajoutez une URL d'écoute HTTP POST dans vos paramètres marchands.

Événements gérés : payment.success, payment.failed.

// Payload JSON transmis par le webhook Nelsius :
{
  "event": "payment.success",
  "data": {
    "transaction_code": "CHK_X8A9P2KL091M",
    "reference": "COMMANDE_99812",
    "amount": 5000,
    "currency": "XAF",
    "status": "completed",
    "operator": "MTN_MOMO_CMR"
  }
}

Codes de Statut HTTP

L'API Nelsius utilise les codes de statut HTTP standardisés.

200 / 201 - Succès

Requête exécutée ou ressource créée.

400 - Paramètre Invalide

Le corps JSON est malformé ou un champ obligatoire est manquant.

401 - Non Autorisé

Clé API manquante ou invalide dans X-Api-Key.

404 - Introuvable

La route ou la référence de transaction est introuvable.

curl -X GET "http://localhost:8000/api/v1/payments/COMMANDE_99812" \
  -H "X-Api-Key: sk_test_your_key_here" \
  -H "Accept: application/json"