Skip to main content

​
JavaScript SDK

Le SDK JavaScript officiel pour intégrer SahelPay dans vos applications Node.js, TypeScript ou Deno.

​
Installation

npm install @sahelpay/sdk
# ou
yarn add @sahelpay/sdk
En attendant la publication sur npm, clonez le repo GitHub :
git clone https://github.com/dione24/sahelpay-sdks.git

​
Configuration

import SahelPay from '@sahelpay/sdk';

const sahelpay = new SahelPay({
  secretKey: process.env.SAHELPAY_SECRET_KEY!,
  environment: 'production' // ou 'sandbox'
});

​
Créer un paiement

const payment = await sahelpay.payments.create({
  amount: 5000,
  currency: 'XOF',
  payment_method: 'ORANGE_MONEY', // ORANGE_MONEY, WAVE, MOOV, CARD
  customer_phone: '+22370123456',
  return_url: 'https://votre-site.com/checkout/return',
  description: 'Commande #123',
});

// Rediriger le client vers Orange Money
window.location.href = payment.redirect_url;

​
Méthodes de paiement disponibles

MéthodeDescriptionPays
ORANGE_MONEYOrange MoneyMali, Sénégal, CI
WAVEWaveMali, Sénégal, CI
MOOVMoov MoneyMali, Bénin, Togo
CARDCarte bancaire (VISA/MC/GIM)Tous
VISACarte VISATous
MASTERCARDCarte MastercardTous
GIM_UEMOACarte GIM-UEMOAUEMOA
SahelPay utilise un Smart Routing automatique. Vous spécifiez la méthode de paiement (ex: ORANGE_MONEY) et SahelPay choisit le meilleur gateway en interne selon le coût et la disponibilité.

​
Vérifier le statut

const status = await sahelpay.getPaymentStatus('txn_abc123');

console.log(status.status); // 'PENDING' | 'SUCCESS' | 'FAILED' | 'EXPIRED'
console.log(status.amount);
console.log(status.providerRef);

​
Vérifier un webhook

// Dans votre handler webhook
export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get('x-sahelpay-signature');

  const result = sahelpay.verifyWebhook(rawBody, signature);

  if (!result.valid) {
    return Response.json({ error: result.error }, { status: 401 });
  }

  const { event, data } = result.payload!;

  if (event === 'payment.success') {
    // Mettre à jour la commande
  }

  return Response.json({ received: true });
}

​
Types TypeScript

import type {
  PaymentResult,
  PaymentStatus,
  WebhookPayload,
  WebhookVerificationResult,
} from '@sahelpay/sdk/merchant';

​
Gestion des erreurs

import { SahelPayError } from '@sahelpay/sdk';

try {
  const payment = await sahelpay.payments.create({ ... });
} catch (error) {
  if (error instanceof SahelPayError) {
    console.log(error.code);    // 'INVALID_AMOUNT'
    console.log(error.message); // 'Montant minimum: 100 FCFA'
  }
}

​
Informations de Routing

Chaque paiement retourne des informations sur le routing utilisé (pour monitoring) : 
const payment = await sahelpay.payments.create({ ... });

console.log(payment.gateway_used);    // Identifiant technique interne
console.log(payment.routing_reason);  // Explication du routing choisi
Ces champs sont informatifs uniquement pour le monitoring. Le choix du routing est automatique et transparent pour vous.

​
Capabilities

Vérifiez les fonctionnalités disponibles pour chaque méthode de paiement : 
import { hasCapability, getMethodsWithCapability } from '@sahelpay/sdk';

// Vérifier si Orange Money supporte les payouts
hasCapability('ORANGE_MONEY', 'payouts'); // true

// Lister les méthodes avec QR code natif
getMethodsWithCapability('qr_code'); // ['WAVE']

​
Paiement par Carte

Pour les paiements par carte, les champs customer_name et customer_email sont requis : 
const payment = await sahelpay.payments.create({
  amount: 10000,
  currency: 'XOF',
  payment_method: 'CARD',
  customer_phone: '+22370123456',
  customer_name: 'Mamadou Diallo',      // Requis pour CARD
  customer_email: '[email protected]', // Requis pour CARD
  return_url: 'https://votre-site.com/checkout/return',
});