Documentation NaabigaPay

Introduction

NaabigaPay (NPay) est un portefeuille de paiement mobile pour le Burkina Faso. Il permet d'envoyer et recevoir de l'argent, de recharger via mobile money, et d'encaisser des paiements par QR ou par lien, aussi bien pour les particuliers que pour les commerces.

NaabigaPay fonctionne en circuit fermé : le payeur règle avec son compte NaabigaPay (solde + code PIN), un peu comme Wave ou une caisse mobile money. Les développeurs peuvent accepter NaabigaPay via l'API.

Comment ça marche

1. Créer un compte : inscription par e-mail, vérification par code à 6 chiffres, puis création d'un code PIN.
2. Recharger : alimentez le portefeuille par mobile money.
3. Payer & envoyer : transférez à un autre compte, scannez un QR marchand, ou réglez un lien de paiement.
4. Encaisser : ouvrez un commerce, générez des QR et des liens, et suivez les paiements reçus.

Pour les particuliers

• Solde et historique des transactions en temps réel.
• Transfert instantané vers un autre compte NaabigaPay.
• Recharge par mobile money.
• Paiement en boutique par scan de QR.
• Sécurité par code PIN et vérification d'identité (KYC).

Pour les commerces

• QR d'encaissement : fixe (le client saisit le montant) ou avec montant prédéfini.
• Liens de paiement : partageables, à montant fixe ou libre (le client saisit, avec min/max optionnels).
• Points de vente & caissiers pour organiser l'encaissement.
• Portail développeur : clés API et webhooks pour automatiser.

Développeurs : vue d'ensemble

Acceptez « Payer avec NaabigaPay » sur votre plateforme web ou mobile. Le schéma d'intégration :

1. Depuis votre serveur, vous créez un lien de paiement pour la commande (API).
2. Vous redirigez le client vers l'URL du lien (web : redirection ; mobile : WebView / onglet in-app).
3. Le client paie avec son compte NaabigaPay.
4. Vous êtes notifié par webhook signé (payment.succeeded) et/ou le client est ramené sur votre return_url.

Démarrage rapide

Depuis l'application NaabigaPay → Mon commerce → Développeur : créez une clé API (commencez en sandbox) et enregistrez une URL de webhook.

Authentification

Toutes les requêtes API utilisent votre clé secrète dans l'en-tête Authorization :

Authorization: Bearer sk_live_xxxxxxxx

Créer un lien de paiement

POST/v1/payment-links

curl https://api.pay.naabiga.com/api/v1/payment-links \
  -H "Authorization: Bearer sk_sandbox_xxx" \
  -H "Idempotency-Key: cmd-8421" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "description": "Commande #8421",
    "reference": "8421",
    "return_url": "https://monsite.com/paiement/merci",
    "cancel_url": "https://monsite.com/paiement/annule"
  }'

Réponse (201) :

{
  "token": "9f3c…",
  "url": "https://pay.naabiga.com/link/9f3c…",
  "amount": 15000,
  "currency": "XOF",
  "reference": "8421",
  "status": "active"
}

Montant libre : omettez amount (le client saisira le montant) et fournissez une description ; bornes optionnelles amount_min / amount_max.

Rediriger le client vers le paiement

Redirigez le client vers le champ url renvoyé :

Après paiement, si return_url est défini, le client y est renvoyé automatiquement. La source de vérité reste le webhook (ci-dessous).

Webhooks

Quand un paiement aboutit, NaabigaPay envoie une requête POST à l'URL de webhook enregistrée dans le portail.

Corps reçu :

{
  "event": "payment.succeeded",
  "data": {
    "reference": "NP-…",          // réf. transaction NaabigaPay
    "amount": 15000,
    "currency": "XOF",
    "merchant_code": "…",
    "description": "Commande #8421",
    "payment_link_token": "9f3c…",
    "merchant_reference": "8421"   // VOTRE référence de commande
  },
  "created_at": "2026-09-21T16:57:11+00:00"
}

Vérifier la signature

Recalculez le HMAC sur le corps brut et comparez avec X-NPay-Signature.

$payload = file_get_contents('php://input');
$sig     = $_SERVER['HTTP_X_NPAY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, $secret);

if (! hash_equals($expected, $sig)) {
    http_response_code(400); exit;
}
$event = json_decode($payload, true);
// $event['data']['merchant_reference'] -> votre commande

const crypto = require('crypto');

app.post('/webhooks/npay',
  express.raw({ type: '*/*' }), (req, res) => {
    const sig = req.headers['x-npay-signature'];
    const expected = crypto.createHmac('sha256', SECRET)
      .update(req.body).digest('hex');
    if (sig !== expected) return res.sendStatus(400);

    const evt = JSON.parse(req.body.toString());
    // evt.data.merchant_reference -> votre commande
    res.sendStatus(200);
});

Bouton « Payer avec NaabigaPay »

Exemple complet minimal : un bouton qui appelle votre serveur (lequel crée le lien) puis redirige le client.

<!-- Bouton -->
<button id="pay-npay">Payer avec NaabigaPay</button>

<script>
document.getElementById('pay-npay').onclick = async () => {
  // Votre serveur crée le lien (garde la clé secrète côté serveur)
  const r = await fetch('/api/creer-paiement', { method:'POST' });
  const { url } = await r.json();
  window.location = url;   // redirige vers NaabigaPay
};
</script>

$ch = curl_init('https://api.pay.naabiga.com/api/v1/payment-links');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . $secretKey,
    'Idempotency-Key: ' . $orderId,
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 15000,
    'reference' => $orderId,
    'return_url' => 'https://monsite.com/merci',
  ]),
]);
$link = json_decode(curl_exec($ch), true);
echo json_encode(['url' => $link['url']]);

Référence API

Paramètres de création d'un lien

FAQ

Le client doit-il avoir un compte NaabigaPay ?

Oui. NaabigaPay est un portefeuille en circuit fermé : le paiement se fait avec le solde du compte NaabigaPay du client, validé par code PIN.

Comment tester sans argent réel ?

Utilisez une clé sk_sandbox_… : les paiements se font en environnement de test.

Comment rapprocher un paiement de ma commande ?

Renseignez reference à la création : il revient dans le webhook sous merchant_reference.