SDK Node.js / TypeScript

SDK officiel pour Node.js. Disponible sur NPM sous @haybtech/sdk.

Intégration par IA (Prompt pour Marchands)

Si vous utilisez un assistant IA (comme Cursor, GitHub Copilot, ChatGPT, Claude, etc.), vous pouvez copier-coller le prompt suivant pour intégrer ce SDK de A à Z dans votre projet :

Agis en tant qu'expert en développement backend Node.js. Je souhaite intégrer la solution de paiement HayBTech (Afrique de l'Ouest) sur mon site marchand de A à Z avec le SDK Node.js `@haybtech/sdk`.

Voici ma stack technique actuelle :
- Framework/Runtime : [ex: Express.js, Next.js, NestJS]
- Base de données & ORM : [ex: PostgreSQL avec Prisma, MongoDB avec Mongoose]
- Table/Schéma de commande : [décrivez brièvement votre structure de table Order]

Tâches à accomplir dans le code généré :
1. **Initialisation & Config** : Charger la clé d'API secrète depuis les variables d'environnement (`HAYBTECH_SECRET_KEY`) et initialiser le SDK.
2. **Création du Paiement (Route Checkout)** : Créer un endpoint `/api/checkout` qui prend un ID de commande, vérifie le montant dans la base de données, appelle `haybtech.payments.create(...)` avec les paramètres requis (merchant_ref, amount, currency='XOF', success_url, failed_url, callback_url/webhook), enregistre la transaction et renvoie l'URL de paiement `payment_url` pour rediriger l'utilisateur.
3. **Webhook de Notification (Route Webhook)** : Créer un endpoint `/api/webhook/haybtech` sécurisé. Il doit :
   - Récupérer le payload brut (raw body) et le header de signature `x-haybtech-signature`.
   - Utiliser `Webhook.constructEvent(payload, signature, secret)` avec le secret de webhook (`HAYBTECH_WEBHOOK_SECRET`) pour valider l'authenticité de la requête et prévenir les attaques par rejeu.
   - Traiter `payment.success` pour passer le statut de la commande en "payée" de manière idempotente (vérifier si déjà payée) et déclencher la livraison/le service.
   - Traiter `payment.failed` pour passer le statut de la commande en "échouée".
   - Renvoyer un statut HTTP 200 en cas de succès.
4. **Sécurité & Gestion des Erreurs** : Intégrer des blocs try/catch avec gestion des exceptions spécifiques (`ApiException`), du logging propre, et sans divulguer d'informations sensibles dans les réponses HTTP d'erreur.

Génère un code propre, structuré, commenté et totalement prêt à l'emploi.

Installation

npm install @haybtech/sdk

Ou avec Yarn :

yarn add @haybtech/sdk

Configuration (Zéro-Config)

Si vous avez HAYBTECH_SECRET_KEY dans votre environnement (via .env), vous pouvez utiliser le SDK sans configuration :

const haybtech = require('@haybtech/sdk')();

(Optionnel) Passer la clé explicitement :

const haybtech = require('@haybtech/sdk')('sk_live_votre_cle');

Créer un paiement

const haybtech = require('@haybtech/sdk')();

async function initierPaiement() {
  try {
    const response = await haybtech.payments.create({
      merchant_ref: 'ORDER-12345',
      amount: 5000,
      currency: 'XOF',
      success_url: 'https://monsite.com/succes',
      failed_url: 'https://monsite.com/echec',
      callback_url: 'https://monsite.com/webhook'
    });

    console.log('Payment URL:', response.data.payment_url);
  } catch (error) {
    console.error('Erreur API:', error.message);
  }
}

Exemple Express complet

const express = require('express');
const haybtech = require('@haybtech/sdk')();

const app = express();
app.use(express.json());

// Endpoint paiement
app.post('/checkout', async (req, res) => {
  try {
    const tx = await haybtech.payments.create({
      merchant_ref: `ORD-${Date.now()}`,
      amount: req.body.amount,
      currency: 'XOF',
      success_url: 'https://monsite.com/succes',
      failed_url: 'https://monsite.com/echec',
      callback_url: 'https://monsite.com/webhook',
    });
    res.redirect(tx.data.payment_url);
  } catch (e) {
    res.status(500).json({ error: 'Initiation du paiement échouée' });
  }
});

// Endpoint webhook (body brut requis)
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const { Webhook } = require('@haybtech/sdk');
  const payload   = req.body.toString();
  const signature = req.headers['x-haybtech-signature'];
  const secret    = process.env.HAYBTECH_WEBHOOK_SECRET;

  try {
    const event = Webhook.constructEvent(payload, signature, secret);

    switch (event.event) {
      case 'payment.success':
        // Marquer la commande comme payée
        break;
      case 'payment.failed':
        // Gérer l'échec
        break;
    }

    res.status(200).send('OK');
  } catch (err) {
    res.status(400).send(`Webhook Error: ${err.message}`);
  }
});

Exemple TypeScript / NestJS

import { Injectable } from '@nestjs/common';
const HayBTech = require('@haybtech/sdk');

@Injectable()
export class PaymentService {
  private readonly hayb = HayBTech(process.env.HAYBTECH_SECRET_KEY);

  async createPayment(amount: number, ref: string) {
    return this.hayb.payments.create({
      merchant_ref: ref,
      amount,
      currency: 'XOF',
      success_url: 'https://monsite.com/succes',
      failed_url:  'https://monsite.com/echec',
    });
  }
}

Vérification webhook

const { Webhook } = require('@haybtech/sdk');

// Important : utiliser le body parser brut pour les endpoints webhook
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const payload   = req.body.toString();
  const signature = req.headers['x-haybtech-signature'];
  const secret    = process.env.HAYBTECH_WEBHOOK_SECRET;

  try {
    const event = Webhook.constructEvent(payload, signature, secret);

    switch (event.event) {
      case 'payment.success':
        // Marquer la commande comme payée
        break;
      case 'payment.failed':
        // Gérer l'échec
        break;
    }

    res.status(200).send('OK');
  } catch (err) {
    res.status(400).send(`Webhook Error: ${err.message}`);
  }
});

Body brut

Tous les frameworks Node parsent le JSON automatiquement. Configurez votre framework pour exposer le body brut (string ou Buffer) sur l'endpoint webhook, sinon la signature ne validera jamais.

Mode test

const haybtech = require('@haybtech/sdk')('sk_test_...'); // Aucun débit réel

Gestion des erreurs

try {
  const response = await haybtech.payments.create(params);
} catch (error) {
  console.error(error.message);    // Message lisible
  console.error(error.statusCode); // HTTP status (400, 422, 500...)
  console.error(error.code);       // ex. "insufficient_funds"
}

Ressources API

Ressource	Description
haybtech.payments	Créer, récupérer, lister et vérifier des transactions
haybtech.webhooks	Gérer vos endpoints de notification
haybtech.refunds	Initier des remboursements
haybtech.payouts	Envoyer des fonds vers un wallet mobile money