Introduction

Base url

https://business.novasend.app/

Bienvenue sur la documentation de l'API Novasend Marchand

Objectifs

L’API Marchand permet aux partenaires d’intégrer des fonctionnalités de paiement et de transfert dans leurs applications ou systèmes internes.

Fonctionnalités

Elle offre notamment les capacités suivantes :

• Déclencher des paiements.
• Effectuer des transferts.
• Recevoir des notifications en temps réel.
• Rembourser une transaction

Environnements (Sandbox vs Production)

Vous pouvez basculer entre l'environnement Sandbox (Test) et Production (Live). Chaque environnement est strictement isolé :

• Les Clés API, Webhooks, Transactions, et Rapports sont distincts pour chaque environnement.
• Rien ne transite d'un environnement à l'autre.
• Cela vous permet de développer et tester sereinement en Sandbox avant de passer en Production.

Authentification

Les API de Novasend utilisent l'authentification HTTP Basic. Chaque requête doit inclure un en‑tête Authorization contenant vos identifiants encodés en Base64, au format username:password

par exemple : Authorization: Basic <base64(username:password)>

Une clé (ou paire d'identifiants) vous est fournie par Novasend pour identifier votre compte marchand. Ne partagez jamais ces identifiants. Ne les exposez pas côté client et stockez‑les uniquement sur des serveurs sécurisés.

• Créer une API

Après vous être connecté à votre tableau de bord, rendez-vous dans l’onglet Paramètres, puis accédez à la section Token et cliquez sur le bouton Nouveau token.

• En-têtes requis

  Authorization Obligatoire pour l’authentification. Utilisez le Base64 suivi de votre clé API : Authorization: Basic <base64(username:password)>

  Content-Type Requis pour les requêtes contenant un corps. La valeur doit être : Content-Type: application/json

  Accept-Language (optionnel) Permet de définir la langue des messages d’erreur. Valeurs supportées : fr, en Exemple : Accept-Language: fr

• Gestion des erreurs

  Lorsqu’une requête API échoue, la réponse inclut les détails de l’erreur dans le code de statut HTTP ainsi que dans le corps du message.

  Clé	Description
  code	Identifiant du code d'erreur, il existe plusieurs. Exemple: (country_not_found).
  message	Contient la description de l'erreur. Exemple (Le pays avec le code C n'existe pas).
  statusCode	Code HTTP associé à l'erreur (404).

  ---

Options de Paiement et Limites

Payin Amounts (CI):

• min: 300 FCFA
• max: 2,000,000 FCFA

Payout Amounts (CI):

• min: 500 FCFA
• max: 1,500,000 FCFA

Payin Amounts (CM):

• min: 200 FCFA
• max: 500,000 FCFA

Payout Amounts (CM):

• min: 200 FCFA
• max: 500,000 FCFA

Côte d'Ivoire - CI

Cameroun -CM

Format du numéro de téléphone

• Côte d'Ivoire - CI

• Cameroun - CM

Les règles de Remboursement :

• Payout (Transfert) : En cas de statut échec lors d'un paiement, Novasend rembourse le montant brut (Montant facturé + les frais) sur le portefeuille du Marchand.
• Payin (Paiement) : En cas de statut échec lors d'un paiement et que le client du Marchand a été débité, Novasend procède à la vérification avec ses partenaires sur le statut de la transaction. Lorsqu'il est constaté que les fonds ont été collectés par le partenaire, Novasend change le statut de la transaction échec en succès avec envoi du callback (webhook), et crédite le compte du Marchand dans un délai maximum de 48 heures.

API Keys

Après vous être connecté à votre tableau de bord, rendez-vous dans l'onglet Paramètres, puis accédez à la section Token et cliquez sur le bouton Nouveau token. Une fois le token créé, la clé générée s'affichera automatiquement dans le tableau des tokens.

Lorsque vous créez une nouvelle clé API, vous ne verrez la clé complète qu'une seule fois. Assurez-vous de le copier sans manquer aucun caractère, car il sera masqué par la suite pour des raisons de sécurité.

Seuls les utilisateurs administrateurs peuvent accéder à la section Paramètres du portail professionnel. Si vous êtes un administrateur mais que vous ne le voyez toujours pas, contactez le support API pour l'activer.

Webhook

Vous pouvez gérer vos webhooks en allant dans les paramêtres et dans l'onglet Webhook. Vous pouvez créer, afficher, supprimer vos wehbook.

Sécurité et Vérification

Pour garantir que les événements de transaction reçus par votre système sont authentiques, vous devez vérifier la signature HMAC.

• À la création : Vous fournissez une Clé secrète. Cette clé est stockée de manière sécurisée et sert à signer les notifications.
• À la livraison : Pour chaque notification, Novasend génère une Signature HMAC à partir de votre clé secrète et l'inclut dans les en-têtes de la requête.
• Sur votre serveur :
  • Récupérez la signature dans les en-têtes.
  • Calculez votre propre signature HMAC à l'aide de la Clé secrète enregistrée lors de la création.
  • Comparez votre signature générée avec celle reçue dans l'en-tête.
  • Si elles correspondent, la transaction est validée.

BON À SAVOIR

Le Secret Webhook est différent de votre Clé API (Secret API). Le secret est propre à chaque webhook et se trouve dans la configuration de celui-ci dans les paramètres du portail Business.

Chaque notification est signée par l'API à l'aide du secret du webhook :

X-Signature-Value: HMAC_SHA256(body, secret)

Côté marchand, vous devez recalculer cette signature pour vérifier l'intégrité du message :

const crypto = require("crypto");

const signature = crypto
  .createHmac("sha256", secret)
  .update(JSON.stringify(body))
  .digest("hex");

if (signature !== headers["x-signature-value"]) {
  throw new Error("Invalid signature");
}

Réponse

{
  "id": "tr_bbodj27lqhckrc7yomyjlo",
  "fees": 0,
  "type": "payin",
  "amount": 306,
  "status": "processing",
  "failure": null,
  "currency": "XOF",
  "customer": {
    "name": "Souleymane Diomande",
    "phoneNumber": "+2250153013761"
  },
  "createdAt": "2026-02-02T09:11:14.793Z",
  "reference": "TRX-69806a329d1b9",
  "paymentUrl": "https://pay.wave.com/c/cos-22rs5qhyr2ej6?a=306&c=XOF&m=NOVASEND%20CI%20%2A%20Conn",
  "chargedAmount": 306,
  "confirmationStatus": "none",
  "confirmationRequired": false
}

• Description des champs de la réponse

• customer

À faire absolument

• Vérifier la signature HMAC avant de traiter la donnée.
• Utiliser un endpoint dédié et sécurisé (HTTPS obligatoire).
• Gérer la rejouabilité (idempotence) de chaque webhook via le champ eventId (optionnel).
• Mettre en place une file d'attente ou un traitement asynchrone côté marchand pour éviter les blocages.