v1.0

Documentation NexPay

Intégrez facilement les paiements mobiles Wave et Orange Money dans votre application

Démarrage rapide

Commencez à accepter des paiements en quelques minutes avec notre API simple et puissante.

1️⃣

Créer un compte

Installez NexPay et créez votre premier projet

2️⃣

Configurer les providers

Ajoutez vos clés API Wave et Orange Money

3️⃣

Faire un paiement

Utilisez l'API pour initier votre premier paiement

Installation

NexPay peut être installé en développement local ou en production avec SSL automatique.

Installation en développement

bash

# Cloner le repository
git clone https://github.com/mouhamedlamotte/nexpay.git
cd nexpay

# Copier le fichier d'environnement
cp .env.example .env

# Démarrer les services
docker compose -f docker-compose-dev.yml up -d

# Accéder à l'application
# http://localhost:9090

Installation en production

bash

# Installation en une commande
curl -fsSL https://raw.githubusercontent.com/mouhamedlamotte/nexpay/main/install.sh | bash -s -- pay.yourdomain.com

Authentification avec clés API

NexPay utilise deux types de clés API pour une sécurité optimale : une clé de lecture (publique) et une clé d'écriture (privée).

READClé de lecture

Peut être utilisée côté client
Vérifier le statut d'un paiement
Récupérer une session

WRITEClé d'écriture

À garder secrète (serveur uniquement)
Initier un paiement
Créer une session de paiement

Utilisation des clés

bash

# Header requis pour toutes les requêtes
x-api-key: YOUR_API_KEY

Guide du Tableau de Bord

Le dashboard vous donne un aperçu complet de votre activité de paiement avec des statistiques en temps réel.

Métriques clés

Volume Total : Montant total des transactions
Transactions : Nombre de transactions
Taux de Réussite : Pourcentage de transactions réussies

Fonctionnalités

Performance par Provider : Répartition par fournisseur
Statistiques Rapides : Montant moyen, nouveaux clients
Transactions récentes : Liste des dernières transactions

Processus de paiement

1. Sélection du mode de paiement

Le client choisit son mode de paiement préféré (Wave, Orange Money, etc.)

2. Paiement via QR Code ou lien direct

Le client peut scanner le QR code avec son application de paiement ou cliquer sur le lien direct.

Configuration Wave

La configuration des providers se fait sur une page dédiée par provider : /wave

Onglet Secrets Configuration

API Key : Votre clé API Wave obtenue depuis le portail développeur Wave

Onglet Webhook Configuration

Deux types d'authentification sont disponibles :

Shared Secret

Authentification simple avec une clé secrète partagée (minimum 20 caractères)

HMAC (Recommandé)

Authentification cryptographique avancée avec vérification d'intégrité

URL du webhook à configurer chez Wave :

bash

https://pay.yourdomain.com/api/v1/webhook/wave

Configuration Orange Money

Onglet Secrets Configuration

Client ID : Votre identifiant client Orange Money
Client Secret : Votre secret client Orange Money
Name : Votre nom marchant Orange Money
Code : Code fournis par Orange Money

Onglet Webhook Configuration

Auto-configuration disponible Si vous activez la configuration automatique, le webhook sera configuré automatiquement chez Orange Money.
vous avez aussi la possibilité de mettre votre propre clée ou laisser nexpay la generer automatiquement.

URL du webhook à configurer chez Orange Money :

bash

https://pay.yourdomain.com/api/v1/webhook/om

Initier un paiement direct

Utilisez cette méthode lorsque vous contrôlez la sélection du provider de paiement dans votre interface.

POST/api/v1/payment/initiate

javascript

const response = await fetch('https://pay.yourdomain.com/api/v1/payment/initiate', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.NEXPAY_WRITE_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,
    userId: '1f31dfd7-aec8-4adf-84ff-4a9c1981be2a',
    name: 'Mouhamed  baba',
    phone: '+22177123456',
    email: 'exemple@email.com',
    client_reference: 'ref-1f31dfd7-aec8-4adf-84ff-4a9c1981be2a',
    projectId: '{{projectId}}',
    currency: 'XOF',
    metadata: { key: 'value', foo: 'bar' },
    successUrl: 'https://example.com/success',
    cancelUrl: 'https://example.com/error',
    provider: 'wave'
  })
});

const data = await response.json();
console.log(data);

Créer une session de paiement

Utilisez cette méthode pour déléguer la sélection du provider à l'interface checkout de NexPay.

POST/api/v1/payment/session/initiate

javascript

const response = await fetch('https://pay.yourdomain.com/api/v1/payment/session/initiate', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.NEXPAY_WRITE_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,
    userId: '1f31dfd7-aec8-4adf-84ff-4a9c1981be2a',
    name: 'Mouhamed  baba',
    phone: '+22177123456',
    email: 'exemple@email.com',
    client_reference: 'ref-1f31dfd7-aec8-4adf-84ff-4a9c1981be2a',
    projectId: '{{projectId}}',
    currency: 'XOF',
    metadata: { key: 'value', foo: 'bar' },
    successUrl: 'https://example.com/success',
    cancelUrl: 'https://example.com/error'
  })
});

const data = await response.json();
window.location.href = data.data.checkoutUrl;

Récupérer les détails d'une session

Retourne toutes les informations associées à une session de paiement.

GET/api/v1/payment/session/:sessionId

javascript

const response = await fetch('https://pay.yourdomain.com/api/v1/payment/session/cmhdpuj6m00069usa10370ldr', {
  headers: { 'x-api-key': 'YOUR_READ_KEY' }
});

const data = await response.json();
console.log(data.data);

Vérifier le statut d'un paiement (Long Polling)

Cette route garde la requête ouverte jusqu’à 60 secondes. Elle répond dès que le statut n’est plus pending.

GET/api/v1/payment/session/:sessionId/status

javascript

const response = await fetch(
  'https://pay.yourdomain.com/api/v1/payment/session/cmhdpuj6m00069usa10370ldr/status',
  { headers: { 'x-api-key': 'YOUR_READ_KEY' } }
);

const data = await response.json();
console.log(data.data.status);

Configuration des webhooks

Les webhooks vous permettent de recevoir des notifications en temps réel sur les événements de paiement.

Le secret webhook est optionnel. S'il n'est pas fourni, il sera généré automatiquement.

Créer un webhook

Accédez à Paramètres du compte → Webhooks
Cliquez sur Nouveau webhook
Renseignez l'URL de votre endpoint
Définissez le nom du header (ex: x-webhook-secret)
Le secret sera généré automatiquement si vous ne le fournissez pas

Attention : Le secret n'est visible qu'une seule fois après la création du webhook. Copiez-le et sauvegardez-le dans un endroit sécurisé.

Événements webhook

Structure d'un événement

json

{
  "type": "payment.succeeded",
  "data": {
    "amount": "100800",
    "client_reference": "nexpay-ref-30-10-2025",
    "status": "SUCCEEDED",
    "resolvedAt": "2025-10-30T17:29:58.109Z",
    "payer": {
      "name": "Jean Dupont",
      "email": "jean@example.com",
      "phone": "+221771234567"
    },
    "provider": {
      "name": "Wave",
      "code": "wave"
    },
    "project": {
      "id": "proj_123",
      "name": "Mon Projet"
    },
    "metadata": {
      "order_id": "ORDER-123"
    }
  }
}

Types d'événements

payment.succeeded

Paiement réussi

payment.failed

Paiement échoué

payment.pending

Paiement en attente

payment.cancelled

Paiement annulé

Vérification des webhooks

Vérifiez toujours la signature des webhooks pour garantir leur authenticité et éviter les attaques.

Exemple Node.js/Express

javascript

const express = require('express');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.NEXPAY_WEBHOOK_SECRET;


app.post('/webhook/nexpay', (req, res) => {
  const receivedSecret = req.headers['x-webhook-secret'];
  
  // Vérifier la signature
  if (receivedSecret !== WEBHOOK_SECRET) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Invalid signature');
  }
  
  const event = req.body;
  
  // Traiter l'événement
  switch (event.type) {
    case 'payment.succeeded':
      console.log('Payment succeeded:', event.data.client_reference);
      // Mettre à jour la commande
      break;
    
    case 'payment.failed':
      console.log('Payment failed:', event.data.client_reference);
      // Notifier l'utilisateur
      break;
  }
  
  // Toujours répondre 200 OK
  res.status(200).send('OK');
});

app.listen(3000);

Exemples d'intégration

Voici des exemples d'intégration dans différents langages de programmation pour créer une session de paiement.

Créer une session de paiement

javascript

const axios = require('axios');

async function createPaymentSession() {
  try {
    const response = await axios.post(
      'https://pay.yourdomain.com/api/v1/payment/session/initiate',
      {
        amount: 5000,
        userId: '1f31dfd7-aec8-4adf-84ff-4a9c1981be2a',
        name: 'Mouhamed Baba',
        phone: '+22177123456',
        email: 'exemple@email.com',
        client_reference: 'ref-1f31dfd7-aec8-4adf-84ff-4a9c1981be2a',
        projectId: '{{projectId}}',
        currency: 'XOF',
        metadata: {
          key: 'value',
          foo: 'bar'
        },
        successUrl: 'https://example.com/success',
        cancelUrl: 'https://example.com/error'
      },
      {
        headers: {
          'x-api-key': process.env.NEXPAY_WRITE_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Checkout URL:', response.data.data.checkoutUrl);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createPaymentSession();

Webhook Handlers

Exemples de handlers webhook pour traiter les événements de paiement.

javascript

const express = require('express');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.NEXPAY_WEBHOOK_SECRET;

app.post('/webhook/nexpay', (req, res) => {
  const signature = req.headers['x-webhook-secret'];
  
  if (signature !== WEBHOOK_SECRET) {
    console.error('Invalid webhook secret');
    return res.status(401).send('Invalid secret');
  }
  
  const event = req.body;
  
  switch (event.type) {
    case 'payment.succeeded':
      console.log('Payment succeeded:', event.data.client_reference);
      break;
    case 'payment.failed':
      console.log('Payment failed:', event.data.client_reference);
      break;
  }
  
  res.status(200).send('OK');
});

app.listen(3000);

Gestion multi-projets

NexPay permet de gérer plusieurs projets avec une seule instance.

Configuration unique des providers

Les providers (Wave, Orange Money) sont configurés une seule fois et partagés entre tous les projets.

Configuration dynamique par projet

Chaque projet peut avoir ses propres webhooks, URLs de redirection et paramètres.

Isolation des données

Les transactions et statistiques sont isolées par projet pour une meilleure organisation.

Dépannage

Les paiements ne fonctionnent pas

Vérifiez que les providers sont correctement configurés (onglets Secrets et Webhook)
Vérifiez que les webhooks sont configurés chez les providers
Testez le provider avec le bouton "Test Payment"
Consultez les logs : docker-compose logs -f

Problème de certificat SSL (Production)

Traefik gère automatiquement les certificats SSL. Si vous rencontrez des problèmes :

Vérifiez que votre domaine pointe bien vers votre serveur
Vérifiez les logs Traefik : docker-compose logs traefik
Attendez quelques minutes pour la génération du certificat
Vérifiez que les ports 80 et 443 sont ouverts

Erreurs d'authentification API

Vérifiez que vous utilisez le bon header : x-api-key
Vérifiez que vous utilisez la bonne clé (lecture ou écriture)
Vérifiez que la clé n'a pas été modifiée dans le .env

Développé avec ❤️ par Mouhamed Lamotte

Version 1.0 • Dernière mise à jour : Novembre 2025