kpay-sdk — Node.js

SDK officiel KPay (Node ≥ 18, zéro dépendance).

Installation

npm install kpay-sdk

Rien d'autre à installer : le package est autonome (aucune dépendance transitive). Types TypeScript inclus.

import { KpayClient } from "kpay-sdk";

const kpay = new KpayClient({
  baseUrl: "https://admin.kpay.site",    // sans /api
  apiKey: process.env.KPAY_API_KEY,
  secretKey: process.env.KPAY_SECRET_KEY,
  gatewaySecret: process.env.KPAY_GATEWAY_SECRET, // pour vérifier les retours
  maxDuration: 300,                      // SEUL paramètre configurable (secondes)
});

Paiement — mode passerelle (recommandé)

const res = await kpay.initPayment({
  amount: 5000,
  externalId: "ORDER-123",
  description: "Commande #123",
  returnUrl: "https://monsite.com/retour",
  cancelUrl: "https://monsite.com/annule",
});
// → rediriger le client vers res.gatewayUrl

Paiement — mode USSD

const res = await kpay.initPayment({
  amount: 5000,
  phoneNumber: "674693625",
  paymentMethod: "MTN_MONEY",
  externalId: "ORDER-123",
});

Retrait

await kpay.initWithdrawal({ amount: 1000, phoneNumber: "674693625", paymentMethod: "ORANGE_MONEY" });

Hybride : webhook + attente asynchrone

Le modèle recommandé reste webhook (résolution instantanée). Le SDK fournit en complément une attente asynchrone non bloquante, bornée par maxDuration :

// 1) Vérifier la signature du retour / webhook
if (!kpay.verifyReturnSignature(req.query)) return res.status(400).end();

// 2) Confirmer le statut final (filet de sécurité, s'arrête au terminal
//    ou au bout de maxDuration)
const final = await kpay.awaitFinalStatus(paymentId, { kind: "payment" });
if (final.status === "COMPLETED") { /* livrer */ }

awaitFinalStatus ne bloque pas l'event-loop et s'arrête dès un statut terminal (COMPLETED|FAILED|CANCELLED|EXPIRED|REFUNDED) ou à l'échéance maxDuration.