SDK Node.js

Le SDK Node.js alphapay-node enveloppe l’API REST AlphaPay (checkout, softpay, liens de paiement, clients, webhooks…) avec retry automatique (backoff exponentiel + gigue sur 429/5xx/erreur réseau), gestion d’idempotence et exceptions typées par cas d’erreur. Écrit en TypeScript, types fournis nativement.

npm install alphapay-node
# ou : yarn add alphapay-node / pnpm add alphapay-node

Chaque exemple ci-dessous est autonome : copiez-le, remplacez process.env.ALPHAPAY_SECRET_KEY par votre clé (sk_test_... en sandbox, sk_live_... en production) et lancez-le avec tsx/ts-node ou après compilation.

1. Checkout (session hébergée)

Crée une page de paiement hébergée par AlphaPay et pré-remplie pour un client précis — l’usage le plus simple pour un e-commerce classique (redirigez le client vers checkout_url).

import { AlphaPayClient } from "alphapay-node";

const alphapay = new AlphaPayClient({ apiKey: process.env.ALPHAPAY_SECRET_KEY! });

async function creerCheckout() {
  const session = await alphapay.checkoutSessions.create(
    {
      amount: 5000,
      currency: "XOF",
      description: "Commande #1042",
      customer_email: "client@exemple.com",
      customer_name: "Ayaba Client",
      customer_phone: "+22900000000",
      return_url: "https://boutique.exemple.com/merci",
      metadata: { order_id: "1042" },
    },
    { idempotencyKey: true }, // génère une clé unique — un retry réseau ne recrée pas de doublon
  );

  console.log("Redirigez le client vers :", session.checkout_url);
  console.log("Slug (à stocker pour retrouver la session) :", session.slug);
  return session;
}

async function suivreCheckout(id: string) {
  const session = await alphapay.checkoutSessions.get(id);
  console.log("Statut :", session.status); // PENDING, PAID, EXPIRED, CANCELLED
}

async function annulerCheckout(id: string) {
  const session = await alphapay.checkoutSessions.cancel(id);
  console.log("Annulée :", session.status === "CANCELLED");
}

2. Softpay (encaissement direct)

Pousse directement une demande de paiement (USSD mobile money) sans page de checkout à afficher — utile pour une app où vous collectez déjà le numéro du client.

import { AlphaPayClient, AlphaPayValidationError } from "alphapay-node";

const alphapay = new AlphaPayClient({ apiKey: process.env.ALPHAPAY_SECRET_KEY! });

async function encaisser() {
  try {
    const payment = await alphapay.transactions.payin.initialize(
      {
        amount: 2500,
        currency: "XOF",
        country: "BJ",
        network: "mtn_bj", // cf. GET /networks/ pour la liste à jour
        description: "Abonnement mensuel",
        customer: {
          email: "client@exemple.com",
          first_name: "Ayaba",
          last_name: "Client",
          phone: "+22900000000",
        },
      },
      { idempotencyKey: true },
    );

    console.log("Paiement initié :", payment.id, payment.status);

    // Sondez jusqu'à confirmation (push USSD confirmé/refusé côté client).
    const result = await alphapay.transactions.payin.verify(payment.id);
    console.log("Statut final :", result.status);
  } catch (err) {
    if (err instanceof AlphaPayValidationError) {
      console.error("Champs invalides :", err.fieldErrors);
    } else {
      throw err;
    }
  }
}

// Réseaux à confirmation en 2 temps (ex. Wizall Sénégal, Coris Bénin).
async function confirmerOtp(paymentId: string, otp: string) {
  const result = await alphapay.transactions.payin.confirmOtp(paymentId, otp);
  console.log("Confirmé :", result.status);
}

3. Lien de paiement

Un lien réutilisable (partageable sur WhatsApp, réseaux sociaux, etc.), avec ses propres champs personnalisés et suivi publicitaire.

import { AlphaPayClient } from "alphapay-node";

const alphapay = new AlphaPayClient({ apiKey: process.env.ALPHAPAY_SECRET_KEY! });

async function creerLien() {
  const link = await alphapay.paymentLinks.create({
    name: "Formation en ligne",
    description: "Accès à vie à la formation",
    amount_type: "FIXED",
    amount: 15000,
    currency: "XOF",
    facebook_pixel_id: process.env.FACEBOOK_PIXEL_ID,
    google_ads_id: process.env.GOOGLE_ADS_ID,
    custom_fields: [
      { key: "email_formation", label: "E-mail pour l'accès", required: true },
    ],
  });

  console.log("Lien partageable :", link.url);
  return link;
}

// Ce que voit la page publique du lien — pas d'auth marchand nécessaire.
async function consulterLienPublic(slug: string) {
  const publicLink = await alphapay.paymentLinks.getPublic(slug);
  console.log(`${publicLink.name} — ${publicLink.amount ?? "montant libre"} ${publicLink.currency}`);
  console.log("Utilisable :", publicLink.is_usable, publicLink.unusable_reason ?? "");
}

// Crée une CheckoutSession one-shot à partir du lien (ex. depuis votre propre
// front public, sans jamais exposer la clé secrète côté client).
async function payerDepuisLien(slug: string) {
  const result = await alphapay.paymentLinks.createPublicCheckout(slug, {
    customer: { email: "client@exemple.com", first_name: "Ayaba", last_name: "Client" },
    custom_field_values: { email_formation: "ayaba@exemple.com" },
  });
  console.log("Session créée :", result.checkout_url);
}

async function listerLiens() {
  const { results } = await alphapay.paymentLinks.list({ is_active: true });
  for (const link of results) console.log(link.name, link.usage_count, "utilisations");
}

4. Solde et grand livre

import { AlphaPayClient, AlphaPayPermissionError } from "alphapay-node";

const alphapay = new AlphaPayClient({ apiKey: process.env.ALPHAPAY_SECRET_KEY! });

async function verifierSoldes() {
  const { results } = await alphapay.balances.list();
  for (const balance of results) {
    console.log(`${balance.country} (${balance.currency}) : ${balance.available_amount} disponible`);
  }
}

async function grandLivre() {
  try {
    // ⚠️ Dashboard-only — lève AlphaPayPermissionError (403) via une clé API,
    // conservé ici pour documenter la forme réelle de l'endpoint.
    await alphapay.balances.ledgerEntries({ country: "BJ" });
  } catch (err) {
    if (err instanceof AlphaPayPermissionError) {
      console.log("Grand livre détaillé : consultable uniquement depuis le dashboard.");
    } else {
      throw err;
    }
  }
}

5. Clients (CRM)

import { AlphaPayClient } from "alphapay-node";

const alphapay = new AlphaPayClient({ apiKey: process.env.ALPHAPAY_SECRET_KEY! });

async function gererClient() {
  // `country` est l'UUID d'un `geo.Country` côté API — PAS un code ISO2 ("BJ").
  const countryId = "00000000-0000-0000-0000-000000000000";

  const customer = await alphapay.customers.create({
    email: "client@exemple.com",
    full_name: "Ayaba Client",
    phone: "+22900000000",
    country: countryId,
  });

  await alphapay.customers.update(customer.id, { phone: "+22900000001" });

  const { results: transactions } = await alphapay.customers.transactions(customer.id, { page_size: 20 });
  console.log(`${transactions.length} transaction(s) pour ce client.`);

  return customer;
}

async function listerClients() {
  const { results } = await alphapay.customers.list({ search: "ayaba" });
  console.log(results.map((c) => c.email));
}

6. Webhooks

Réception et vérification d’un webhook entrant (exemple avec un serveur HTTP natif Node ; adaptez req/res à Express/Fastify au besoin — le principe ne change pas : toujours vérifier la signature sur le corps brut, avant tout JSON.parse).

import { createServer } from "node:http";
import {
  AlphaPayWebhookSignatureError,
  verifyWebhookSignature,
  type WebhookEvent,
} from "alphapay-node";

const WEBHOOK_SECRET = process.env.ALPHAPAY_WEBHOOK_SECRET!;

const server = createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks).toString("utf8");

    try {
      const event: WebhookEvent = verifyWebhookSignature({
        payload: rawBody,
        signature: req.headers["x-webhook-signature"] as string,
        timestamp: req.headers["x-webhook-timestamp"] as string,
        secret: WEBHOOK_SECRET,
      });

      switch (event.event) {
        case "payment.succeeded":
          console.log("Paiement réussi :", event.data);
          break;
        case "payment.failed":
          console.log("Paiement échoué :", event.data);
          break;
        default:
          console.log("Événement reçu :", event.event);
      }

      res.writeHead(200).end("ok");
    } catch (err) {
      if (err instanceof AlphaPayWebhookSignatureError) {
        console.error("Webhook rejeté :", err.message);
        res.writeHead(400).end("signature invalide");
      } else {
        throw err;
      }
    }
  });
});

server.listen(3000);

Consultation en lecture (CRUD d’écriture réservé au dashboard) :

import { AlphaPayClient } from "alphapay-node";

const alphapay = new AlphaPayClient({ apiKey: process.env.ALPHAPAY_SECRET_KEY! });

async function inspecterWebhooks() {
  const { results: webhooks } = await alphapay.webhookEndpoints.list();
  for (const webhook of webhooks) console.log(webhook.url, webhook.is_active);

  const { results: logs } = await alphapay.webhookEndpoints.logs.list({ status: "FAILED" });
  console.log(`${logs.length} livraison(s) échouée(s).`);
}

7. Reversements et transferts entre wallets

Ces deux ressources sont entièrement inaccessibles via clé API (403 dashboard_only sur toutes leurs méthodes, y compris en lecture) — elles ne peuvent être pilotées que depuis le dashboard AlphaPay par un compte utilisateur connecté. Elles restent dans le SDK pour documenter la forme réelle des endpoints, pas pour un usage serveur automatisé.

import { AlphaPayClient, AlphaPayPermissionError } from "alphapay-node";

const alphapay = new AlphaPayClient({ apiKey: process.env.ALPHAPAY_SECRET_KEY! });

async function tenterReversement() {
  try {
    await alphapay.settlements.create(
      { country: "BJ", requested_amount: 10000, payout_method: "mtn_bj" },
      { idempotencyKey: true },
    );
  } catch (err) {
    if (err instanceof AlphaPayPermissionError) {
      console.log("Reversement : dashboard uniquement, pas via clé API.");
    } else {
      throw err;
    }
  }
}

async function tenterTransfertWallet() {
  try {
    await alphapay.walletTransfers.create({
      from_country: "BJ",
      to_country: "CI",
      from_amount: 5000,
    });
  } catch (err) {
    if (err instanceof AlphaPayPermissionError) {
      console.log("Transfert entre wallets : dashboard uniquement, pas via clé API.");
    } else {
      throw err;
    }
  }
}

8. Clés API et whitelist IP

apiKeys.list/create/get/revoke/delete sont dashboard-only (403 via clé API — une clé compromise ne doit pas pouvoir en créer d’autres). Seule ipWhitelist fonctionne via clé API, et elle est requise pour les payouts.

import { AlphaPayClient } from "alphapay-node";

const alphapay = new AlphaPayClient({ apiKey: process.env.ALPHAPAY_SECRET_KEY! });

async function gererWhitelist() {
  const entry = await alphapay.apiKeys.ipWhitelist.create({
    ip_address: "203.0.113.42",
    label: "Serveur de production",
  });

  await alphapay.apiKeys.ipWhitelist.update(entry.id, { status: "ACTIVE" });

  const { results } = await alphapay.apiKeys.ipWhitelist.list();
  console.log(results.map((e) => `${e.ip_address} (${e.status})`));
}

9. Gestion des erreurs

Toutes les erreurs API héritent de AlphaPayError — vérifiez le type le plus spécifique d’abord.

import {
  AlphaPayClient,
  AlphaPayAuthenticationError,
  AlphaPayConnectionError,
  AlphaPayError,
  AlphaPayIdempotencyError,
  AlphaPayNotFoundError,
  AlphaPayPermissionError,
  AlphaPayRateLimitError,
  AlphaPayServerError,
  AlphaPayValidationError,
} from "alphapay-node";

const alphapay = new AlphaPayClient({ apiKey: process.env.ALPHAPAY_SECRET_KEY! });

async function appelSecurise() {
  try {
    return await alphapay.checkoutSessions.get("id-inexistant");
  } catch (err) {
    if (err instanceof AlphaPayNotFoundError) {
      console.log("Session introuvable.");
    } else if (err instanceof AlphaPayValidationError) {
      console.log("Erreurs par champ :", err.fieldErrors);
    } else if (err instanceof AlphaPayAuthenticationError) {
      console.log("Clé API invalide ou manquante.");
    } else if (err instanceof AlphaPayPermissionError) {
      console.log("Action réservée au dashboard :", err.code); // ex. "dashboard_only"
    } else if (err instanceof AlphaPayIdempotencyError) {
      console.log("Idempotency-Key déjà utilisée avec un payload différent.");
    } else if (err instanceof AlphaPayRateLimitError) {
      console.log(`Trop de requêtes, réessayez dans ${err.retryAfter ?? "quelques"}s.`);
    } else if (err instanceof AlphaPayServerError) {
      console.log("Erreur côté AlphaPay — déjà retentée automatiquement.");
    } else if (err instanceof AlphaPayConnectionError) {
      console.log("Impossible de joindre l'API (réseau/DNS/timeout).");
    } else if (err instanceof AlphaPayError) {
      console.log(`${err.status} ${err.code ?? ""}: ${err.message}`);
    } else {
      throw err; // erreur non-AlphaPay — ne jamais l'avaler silencieusement
    }
    return null;
  }
}

Le client retente déjà automatiquement (backoff exponentiel + gigue) sur 429/5xx/erreur réseau — configurable via maxRetries dans les options du client. Les erreurs ci-dessus ne surviennent donc qu’après épuisement de ces tentatives automatiques.

Prise en main

SDKs & Intégration

Sommaire

1. Checkout (session hébergée)

2. Softpay (encaissement direct)

3. Lien de paiement

4. Solde et grand livre

5. Clients (CRM)

6. Webhooks

7. Reversements et transferts entre wallets

8. Clés API et whitelist IP

9. Gestion des erreurs

​Sommaire

​1. Checkout (session hébergée)

​2. Softpay (encaissement direct)

​3. Lien de paiement

​4. Solde et grand livre

​5. Clients (CRM)

​6. Webhooks

​7. Reversements et transferts entre wallets

​8. Clés API et whitelist IP

​9. Gestion des erreurs

Sommaire

1. Checkout (session hébergée)

2. Softpay (encaissement direct)

3. Lien de paiement

4. Solde et grand livre

5. Clients (CRM)

6. Webhooks

7. Reversements et transferts entre wallets

8. Clés API et whitelist IP

9. Gestion des erreurs