Consultation du Solde

Cet endpoint permet au marchand de consulter en temps réel le solde de son compte API (ou de plusieurs sous-comptes si la plateforme le permet).

Il est souvent utilisé avant d’exécuter un payout ou pour vérifier la capacité de règlement disponible.

GET /v1/balance

Authentification

Élément	Détail
Auth	✅ Requiert un en-tête `Authorization: Basic base64(api_key:api_client)`
Payload	Aucun
Version	`/v1/`
Taux limite conseillé	1 requête toutes les 10 secondes maximum (éviter les appels massifs)

Objectif

Vérifier le solde actuel du compte marchand.
S’assurer que le solde disponible permet d’exécuter un paiement ou transfert.
Suivre les mouvements financiers du compte (par exemple pour afficher dans un tableau de bord).
Identifier les sous-comptes rattachés (ex. par devise ou par activité).

Exemple de Requête

curl -X GET https://api.novasend.app/v1/balance \
  -H "Authorization: Basic base64(api_key:api_client)" \
  -H "Content-Type: application/json"

Exemple de Réponse

[
  {
    "balance": 4676,
    "availableBalance": 4676,
    "reference": "merchant_gh8jpoipkrxhjsm0",
    "currency": "XOF"
  }
]

Interprétation des Champs

Champ	Type	Description
balance	`number`	Solde total du compte, incluant les montants en attente (transactions non encore réglées).
availableBalance	`number`	Solde réellement disponible pour de nouvelles opérations (hors montants bloqués).
reference	`string`	Identifiant du compte marchand ou du sous-compte associé.
currency	`string`	Devise du solde (`XOF`, `USD`, `EUR`, etc.).

💡 Dans certains cas, un marchand peut avoir plusieurs soldes selon les devises ou les environnements (Prod / Sandbox).

Différence entre `balance` et `availableBalance`

Élément	Description
balance	Montant global incluant les fonds en cours de règlement (par exemple, des transactions “processing”).
availableBalance	Montant réellement utilisable immédiatement pour exécuter un payout, sans risquer de rejet.

Exemple :

balance = 10,000
availableBalance = 7,000

→ Cela signifie que 3,000 XOF sont encore en attente de règlement (par exemple, un paiement non confirmé).

Cas d’Utilisation Typiques

| Cas d’usage | Description |

| --- | --- | | Avant un payout | Vérifier que availableBalance ≥ montant + frais avant d’émettre le transfert. | | Dashboard marchand | Afficher le solde en temps réel dans un portail ou une app mobile. | | Conciliation | Comparer les soldes reçus via API et ceux de la base de données locale. | | Prévention des erreurs | Empêcher un paiement si le solde est insuffisant. |

Réponses Multiples

L’API peut retourner plusieurs objets dans le tableau si le marchand dispose de comptes multi-devises ou de sous-comptes segmentés (par région, produit ou service).

Exemple :

[
  {
    "balance": 4676,
    "availableBalance": 4676,
    "reference": "merchant_gh8jpoipkrxhjsm0",
    "currency": "XOF"
  },
  {
    "balance": 1230,
    "availableBalance": 980,
    "reference": "merchant_usd_ahjs87s2",
    "currency": "USD"
  }
]

Erreurs Possibles

Code HTTP	Message	Cause probable	Action recommandée
401	Unauthorized	Clé API invalide ou expirée	Vérifier les credentials
403	Forbidden	Compte désactivé	Contacter le support
404	Not Found	Aucun compte trouvé pour cette API key	Vérifier la configuration
500	Internal Server Error	Erreur temporaire	Réessayer plus tard

Sécurité et Bonnes Pratiques

Ne jamais exposer le api_key côté frontend.
Toujours utiliser la clé de production distincte de celle du sandbox.
Mettre en cache le solde si vous affichez l’information fréquemment (ex. dashboard).
Mettre en place une alerte interne si availableBalance descend sous un certain seuil.

Diagramme Simplifié

Transfert (Payout)Remboursement (Refund)