FluxPay SDK - JavaScript/TypeScript

SDK officiel FluxPay pour JavaScript et TypeScript. Communique avec l'API FluxPay via Kong Gateway.

Installation

npm install @fluxpay/sdk
# ou
yarn add @fluxpay/sdk
# ou
pnpm add @fluxpay/sdk

Utilisation Basique

import FluxPay from '@fluxpay/sdk';

// Initialiser le client
const client = new FluxPay({
  apiKey: 'sk_live_...',
  baseURL: 'https://api.fluxpay.com', // Kong Gateway (point d'entrée unique)
  timeout: 30000,
  retries: 3,
  rateLimitRetry: true,
});

// Créer un paiement
const payment = await client.payments.create({
  amount: 5000,
  currency: 'XOF',
  payment_method: 'mobile_money',
  payment_method_details: {
    provider: 'mtn',
    phone_number: '+2250712345678',
  },
  customer: {
    email: '[email protected]',
    name: 'John Doe',
  },
  metadata: {
    order_id: 'order_123',
  },
});

console.log('Payment created:', payment);

Resources Disponibles

Payments

// Créer un paiement
const payment = await client.payments.create({...});

// Récupérer un paiement
const payment = await client.payments.retrieve('pay_123');

// Lister les paiements
const payments = await client.payments.list({ page: 1, page_size: 20 });

// Remboursement
const refund = await client.payments.refund('pay_123', 2500);

Merchants

// Récupérer un marchand
const merchant = await client.merchants.retrieve('merchant_123');

// Dashboard marchand
const dashboard = await client.merchants.dashboard('merchant_123');

Webhooks

// Créer un webhook
const webhook = await client.webhooks.create({
  url: 'https://example.com/webhook',
  events: ['payment.completed', 'payment.failed'],
});

// Valider la signature d'un webhook
const isValid = client.webhooks.verifySignature(
  request.body,
  request.headers['x-fluxpay-signature'],
  webhookSecret
);

Wallet

// Dépôt
const deposit = await client.wallet.deposit('wallet_123', 10000, 'XOF');

// Retrait
const withdrawal = await client.wallet.withdraw('wallet_123', 5000, 'XOF');

// Transactions
const transactions = await client.wallet.transactions('wallet_123');

Ledger (Admin uniquement) ⚠️

Nécessite JWT avec is_staff=true :

// Définir le token JWT
client.setJWTToken('your_jwt_token');

// Initialiser le plan comptable
await client.ledger.accounts.initialize();

// Lister les comptes
const accounts = await client.ledger.accounts.list({ account_type: 'ASSET' });

// Obtenir le solde d'un compte
const balance = await client.ledger.accounts.balance('1001', {
  date: '2025-12-10',
  currency: 'XOF',
});

// Créer une écriture comptable
const journalEntry = await client.ledger.journalEntries.create({
  entry_date: '2025-12-10',
  description: 'Paiement transaction XYZ',
  lines: [
    {
      account_code: '1101',
      debit: 1000.0,
      credit: 0.0,
      description: 'Créance client',
    },
    {
      account_code: '2001',
      debit: 0.0,
      credit: 1000.0,
      description: 'Dette marchand',
    },
  ],
  currency: 'XOF',
});

// Générer un bilan
const balanceSheet = await client.ledger.reports.balanceSheet({
  date: '2025-12-10',
  currency: 'XOF',
});

Gestion des Erreurs

import {
  APIError,
  RateLimitError,
  AuthenticationError,
  PermissionError,
} from '@fluxpay/sdk';

try {
  const payment = await client.payments.create({...});
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Rate limit exceeded. Retry after:', error.retryAfter);
  } else if (error instanceof AuthenticationError) {
    console.log('Authentication failed');
  } else if (error instanceof PermissionError) {
    console.log('Insufficient permissions');
  } else if (error instanceof APIError) {
    console.log('API Error:', error.statusCode, error.message);
  }
}

Rate Limiting

Le SDK gère automatiquement les erreurs 429 (Rate Limit) avec retry automatique.

Limites par service :

• Payments : 50 req/sec, 2000 req/min, 100000 req/hour
• Merchants : 100 req/min, 5000 req/hour
• Wallet : 200 req/min, 10000 req/hour
• Ledger : 30 req/min, 500 req/hour (plus restrictif)

Kong Gateway

⚠️ Important : Le SDK communique exclusivement avec Kong Gateway (https://api.fluxpay.com), qui route les requêtes vers les services backend appropriés.

Toutes les requêtes passent par Kong, qui gère :

• Authentification (JWT, API Keys)
• Rate Limiting
• Routing vers les services
• Monitoring et logging

Documentation

• API Reference
• Plan d'Implémentation
• Exemples

Support

• Issues : GitHub Issues
• Documentation : docs/PLAN_IMPLEMENTATION_SDK.md

Licence

MIT