nexera-pay

SDK JavaScript/TypeScript officiel pour Nexera Pay — API d'encaissement RDC : Mobile Money (M-Pesa, Airtel Money, Orange Money, Africell) + Carte bancaire (Visa/Mastercard 3-D Secure, PCI DSS SAQ-A). Une seule intégration REST, tous les rails locaux.

Installation

npm install nexera-pay

Quickstart

import { NexeraPay } from "nexera-pay";

const nexera = new NexeraPay({
  apiKey: process.env.NEXERA_PAY_API_KEY!,   // nex_test_... ou nex_live_...
  secret: process.env.NEXERA_PAY_SECRET!,
});

// Créer un paiement Mobile Money (STK)
const payment = await nexera.payments.create({
  amount: 10000,           // 100.00 USD en cents
  currency: "USD",
  method: "mobile_money",
  operator: "mpesa",
  phone: "243812345001",
  reference: "INV-2026-0001",
  description: "Facture #INV-2026-0001",
});

console.log(payment.id, payment.status);   // pay_xxxx  processing

Créer un paiement carte (hosted checkout)

const payment = await nexera.payments.create({
  amount: 50000,
  currency: "USD",
  method: "card",
  reference: "INV-002",
  customer_email: "[email protected]",
  customer_name: "Jean Kabala",
  return_url: "https://monsite.cd/facture/002",
});

// Rediriger le client :
window.location.href = payment.checkout_url!;

Vérifier un webhook

import express from "express";
import { Webhooks } from "nexera-pay";

app.post("/webhooks/nexera", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.header("X-Nexera-Signature");
  const bodyStr = req.body.toString();

  if (!Webhooks.verifySignature(process.env.NEXERA_WEBHOOK_SECRET!, signature!, bodyStr)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(bodyStr);
  if (event.type === "payment.succeeded") {
    const tx = event.data.object;
    // Marquer la facture tx.reference comme payée dans ta DB
  }
  res.status(200).send("ok");
});

Payout B2C (marchand → client)

const payout = await nexera.payouts.create({
  amount: 100,
  currency: "CDF",
  method: "mobile_money",
  operator: "mpesa",
  phone: "243828584688",
  reference: "REMB-001",
  description: "Remboursement produit défectueux",
});

Refund

// Refund total
await nexera.refunds.create("pay_xxx");

// Refund partiel
await nexera.refunds.create("pay_xxx", { amount: 5000, reason: "Article manquant" });

Balance

const bal = await nexera.balance.get();
console.log(bal.available.USD, bal.available.CDF);   // en cents

Sandbox (mode test)

En mode test (clé nex_test_...), les MSISDN suivants déclenchent des scenarios déterministes :

| MSISDN | Résultat | |--------|----------| | ...001 | Succès en 3s | | ...002 | Failed immédiat | | ...003 | Timeout puis failed (60s) | | ...004 | Failed (wrong PIN) | | ...005 | Succès en 10s |

Gestion d'erreurs

import { NexeraPay, SignatureError, RateLimitError, ValidationError } from "nexera-pay";

try {
  const p = await nexera.payments.create({ ... });
} catch (e) {
  if (e instanceof RateLimitError) {
    console.log(`Rate limited, retry dans ${e.retryAfter}s`);
  } else if (e instanceof ValidationError) {
    console.log("Validation failed:", e.detail);
  } else if (e instanceof SignatureError) {
    // Ta clé/secret est mauvaise ou le timestamp système est décalé
  }
}

Docs complètes

https://docs.nexera.africa/pay

License

MIT