Consulter votre solde

L'endpoint Solde renvoie l'argent disponible sur votre compte marchand Tchin, ventilé pays par pays, ainsi qu'un total consolidé. Il est idéal pour alimenter votre propre tableau de bord, afficher un solde en temps réel à vos équipes, ou vérifier qu'un pays dispose des fonds nécessaires avant de lancer un déboursement.

Chez Tchin, votre trésorerie n'est pas un pot commun : chaque pays possède son propre solde. Les encaissements réalisés au Sénégal alimentent le solde Sénégal, ceux du Togo alimentent le solde Togo, etc. Un retrait ne peut être financé que par le solde du pays correspondant au moyen de paiement choisi. Cet endpoint vous donne donc la photo exacte, pays par pays, indispensable pour piloter vos reversements.

Endpoint

GET /api/v1/balance

Aucun paramètre n'est requis. L'authentification se fait, comme pour tous les appels, via vos deux en-têtes TCHIN-PUBLIC-KEY et TCHIN-PRIVATE-KEY. Les montants sont exprimés en entiers FCFA (XOF ; XAF au Cameroun), sans décimales.

Requête

cURL

curl -H "TCHIN-PUBLIC-KEY: tchin_pk_xxxxxxxx" \
     -H "TCHIN-PRIVATE-KEY: tchin_sk_xxxxxxxx" \
     -H "Accept: application/json" \
  https://tchin.tech/api/v1/balance

PHP

<?php
// Récupérer le solde du marchand, ventilé par pays
$ch = curl_init('https://tchin.tech/api/v1/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'TCHIN-PUBLIC-KEY: '.getenv('TCHIN_PUBLIC_KEY'),
        'TCHIN-PRIVATE-KEY: '.getenv('TCHIN_SECRET_KEY'),
        'Accept: application/json',
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($data['success'])) {
    echo "Solde total : ".$data['total']." ".$data['currency']."\n";

    // Indexer les soldes par code pays pour un accès rapide
    $parPays = [];
    foreach ($data['balances'] as $b) {
        $parPays[$b['country']] = $b['balance'];
    }

    // Exemple : vérifier le solde du Sénégal avant un déboursement
    $soldeSN = $parPays['SN'] ?? 0;
    echo "Solde Sénégal : ".$soldeSN." FCFA\n";
}

Node.js

// Node.js (fetch, async/await)
async function getBalance() {
  const r = await fetch('https://tchin.tech/api/v1/balance', {
    headers: {
      'TCHIN-PUBLIC-KEY': process.env.TCHIN_PUBLIC_KEY,
      'TCHIN-PRIVATE-KEY': process.env.TCHIN_SECRET_KEY,
      'Accept': 'application/json',
    },
  });
  const data = await r.json();

  if (data.success) {
    console.log(`Solde total : ${data.total} ${data.currency}`);

    // Indexer par code pays
    const parPays = Object.fromEntries(
      data.balances.map(b => [b.country, b.balance])
    );

    // Vérifier le solde du Sénégal avant un déboursement
    const soldeSN = parPays['SN'] ?? 0;
    console.log(`Solde Sénégal : ${soldeSN} FCFA`);
  }
  return data;
}

getBalance();

Python

# Python (requests)
import os, requests

r = requests.get('https://tchin.tech/api/v1/balance',
    headers={
        'TCHIN-PUBLIC-KEY': os.environ['TCHIN_PUBLIC_KEY'],
        'TCHIN-PRIVATE-KEY': os.environ['TCHIN_SECRET_KEY'],
        'Accept': 'application/json',
    })
data = r.json()

if data.get('success'):
    print(f"Solde total : {data['total']} {data['currency']}")

    # Indexer les soldes par code pays
    par_pays = {b['country']: b['balance'] for b in data['balances']}

    # Vérifier le solde du Sénégal avant un déboursement
    solde_sn = par_pays.get('SN', 0)
    print(f"Solde Sénégal : {solde_sn} FCFA")

Réponse

La réponse contient le total, la devise, puis un tableau balances avec une entrée par pays où vous êtes actif (jusqu'à 7 pays).

JSON

{
  "success": true,
  "currency": "XOF",
  "total": 125000,
  "balances": [
    { "country": "SN", "name": "Sénégal",        "balance": 60000 },
    { "country": "CI", "name": "Côte d'Ivoire",   "balance": 25000 },
    { "country": "BJ", "name": "Bénin",           "balance": 15000 },
    { "country": "BF", "name": "Burkina Faso",    "balance": 10000 },
    { "country": "TG", "name": "Togo",            "balance": 8000  },
    { "country": "ML", "name": "Mali",            "balance": 5000  },
    { "country": "CM", "name": "Cameroun",        "balance": 2000  }
  ]
}

Champs de la réponse

Champ	Type	Description
`success`	booléen	Indique si l'appel a abouti. Vérifiez-le toujours avant de lire les autres champs.
`currency`	texte	Devise des montants. Toujours `XOF` (le Cameroun, en XAF, partage la même valeur nominale).
`total`	entier	Somme de tous les soldes pays, en FCFA. C'est votre trésorerie Tchin globale.
`balances`	tableau	Liste des soldes détaillés, un objet par pays.
`balances[].country`	texte	Code ISO du pays (`SN`, `CI`, `BJ`, `BF`, `TG`, `ML`, `CM`).
`balances[].name`	texte	Nom lisible du pays (ex. « Sénégal »), pratique pour l'affichage.
`balances[].balance`	entier	Solde disponible dans ce pays, en FCFA. C'est le montant mobilisable pour un déboursement dans ce pays.

Cas d'usage : vérifier un solde avant un déboursement

Un déboursement débite le solde du pays correspondant au withdraw_mode. Par exemple, un retrait via wave-senegal puise dans votre solde Sénégal. Si ce solde est insuffisant, l'appel à l'initiation du retrait échoue avec une erreur 400 :

Erreur 400

{ "success": false, "message": "Solde insuffisant sur le pays SN.", "balance": 3000 }

Pour éviter ce refus, consultez le solde du pays visé juste avant d'initier le retrait, et comparez-le au montant à reverser. La pré-vérification côté serveur ressemble à ceci :

PHP — pré-vérification

<?php
// Pré-vérifier le solde du pays AVANT d'initier un déboursement,
// pour éviter une erreur 400 "Solde insuffisant sur le pays SN.".
$montant = 4500;      // ce que vous voulez reverser
$pays    = 'SN';      // pays du withdraw_mode choisi (ex: wave-senegal -> SN)

$ch = curl_init('https://tchin.tech/api/v1/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'TCHIN-PUBLIC-KEY: '.getenv('TCHIN_PUBLIC_KEY'),
        'TCHIN-PRIVATE-KEY: '.getenv('TCHIN_SECRET_KEY'),
        'Accept: application/json',
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

$soldePays = 0;
foreach ($data['balances'] as $b) {
    if ($b['country'] === $pays) { $soldePays = $b['balance']; break; }
}

if ($soldePays >= $montant) {
    // OK : on peut initier le déboursement sur ce pays
    // ... appel à POST /disburse/initiate ...
} else {
    // Solde insuffisant : proposez un rechargement ou un autre pays
    echo "Solde $pays insuffisant : $soldePays FCFA (requis : $montant)\n";
}

⚠️ Le solde peut évoluer entre votre lecture et l'exécution du retrait (autres transactions en cours). La pré-vérification réduit fortement le risque de 400, mais ne le garantit pas à 100 % : gérez toujours proprement le cas d'erreur renvoyé par le déboursement.

Bonnes pratiques

Appelez cet endpoint depuis votre serveur uniquement : vos clés (surtout la clé privée) ne doivent jamais transiter par un navigateur ou une application mobile.
Rafraîchissez le solde à la demande (ouverture du dashboard, avant un reversement) plutôt qu'en boucle serrée, afin de ménager vos quotas.
Indexez le tableau balances par country pour retrouver instantanément le solde d'un pays donné.
Affichez les montants tels quels (entiers FCFA), sans décimales ni conversion.
Un pays absent du tableau balances, ou à 0, signifie qu'aucun fonds n'y est mobilisable : rechargez-le (via vos encaissements) ou choisissez un autre pays.

Erreurs possibles

Code	Signification
`401`	Clés manquantes ou invalides.
`403`	Compte suspendu.
`500`	Erreur serveur temporaire : réessayez.

Le détail complet des codes est décrit sur la page Erreurs & statuts.

Et ensuite ?

Une fois le solde du pays confirmé, vous pouvez lancer un reversement en toute sérénité. Rendez-vous sur la page Retrait / Déboursement pour initier, soumettre et suivre un déboursement.