Documentation de l'API Tchin

Bienvenue 👋. Tchin est un agrégateur de paiement Mobile Money pour l'Afrique de l'Ouest et centrale. Grâce à une seule intégration, vous accédez à tous les grands opérateurs — Orange Money, MTN, Moov, Wave, Yas (T‑Money / Free Money), Wizall, Djamo, Expresso — répartis sur 7 pays. Vous n'avez pas à contracter, ni à intégrer, chaque opérateur un par un : Tchin unifie tout derrière une API REST claire.

Avec l'API Tchin, vous pouvez :

• Encaisser — faire payer vos clients par Mobile Money via une page de paiement sécurisée et hébergée par Tchin (checkout hébergé).
• Reverser (débourser) — envoyer de l'argent vers le numéro Mobile Money d'un bénéficiaire (paiement de vendeurs, remboursements, salaires, gains…).
• Consulter votre solde — connaître à tout moment le solde disponible, détaillé pays par pays.

Cette API convient aussi bien à un site e‑commerce, un back‑office, qu'à une application mobile (Android, iOS, Flutter). Toute la logique sensible reste côté serveur ; le client, lui, ne voit qu'une page de paiement.

Sommaire

Cette documentation est organisée en pages thématiques. Parcourez‑les dans l'ordre pour une première intégration, ou allez directement à ce dont vous avez besoin :

• Encaissement — créer un paiement et faire payer vos clients.
• Retrait / Déboursement — envoyer de l'argent à un bénéficiaire et consulter le solde.
• Webhooks — recevoir et authentifier les notifications de paiement.
• Bubble (no‑code) — intégrer Tchin sans écrire de code serveur.
• Erreurs & statuts — codes HTTP, statuts et dépannage.

1. Prérequis

Avant d'appeler l'API en production, assurez‑vous d'avoir :

• Un compte Tchin vérifié — votre dossier KYC doit être approuvé pour passer en mode réel (live) et pour débourser.
• Au moins une application créée dans votre tableau de bord (menu API). C'est elle qui porte vos clés et votre URL de webhook.
• Un serveur capable d'émettre des requêtes HTTPS (PHP, Node.js, Python, etc.) et d'exposer une URL publique pour recevoir les webhooks.

2. Obtenir vos clés d'API

Rendez‑vous dans votre tableau de bord → menu API → Créer une application (logo, nom, description, URL de webhook). Cliquez ensuite sur Voir : un code de vérification vous est envoyé par email (valable 1 h), puis vos deux clés s'affichent :

• tchin_pk_… — clé publique. Elle identifie votre application.
• tchin_sk_… — clé secrète. Elle authentifie vos requêtes et doit rester strictement côté serveur : jamais dans une page web, un dépôt Git public, ni une application mobile.

Vous pouvez créer plusieurs applications (par exemple une par site ou par environnement). Chaque application possède ses propres clés et son propre webhook, ce qui vous permet de cloisonner vos projets.

3. Authentification

L'API n'utilise ni cookie ni token de session : chaque requête doit transporter vos deux clés dans les en‑têtes HTTP. Pour les requêtes qui envoient un corps JSON (les POST), ajoutez également Content-Type et Accept :

TCHIN-PUBLIC-KEY: tchin_pk_xxxxxxxx
TCHIN-PRIVATE-KEY: tchin_sk_xxxxxxxx
Content-Type: application/json
Accept: application/json

• Clés manquantes ou invalides → réponse 401.
• Compte suspendu → réponse 403.

Voici un premier appel complet et authentifié : GET /api/v1/balance, qui renvoie votre solde par pays. Il illustre exactement comment envoyer vos clés dans chaque langage.

cURL

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

PHP

<?php
// Un simple appel authentifié : consulter votre solde par pays.
// La clé secrète reste côté serveur (variable d'environnement).
$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'];
}

Node.js

// Node.js (fetch natif, Node 18+). Les clés proviennent de l'environnement.
const res = 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 res.json();
if (data.success) {
  console.log(`Solde total : ${data.total} ${data.currency}`);
  for (const b of data.balances) {
    console.log(`${b.name} (${b.country}) : ${b.balance}`);
  }
}

Python

# Python (requests). Les clés sont lues depuis l'environnement.
import os, requests

res = 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 = res.json()
if data.get('success'):
    print('Solde total :', data['total'], data['currency'])
    for b in data['balances']:
        print(b['name'], b['country'], ':', b['balance'])

Réponse

{
  "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": 10000 },
    { "country": "BF", "name": "Burkina Faso",   "balance":  8000 },
    { "country": "TG", "name": "Togo",           "balance":  7000 },
    { "country": "ML", "name": "Mali",           "balance":  5000 },
    { "country": "CM", "name": "Cameroun",       "balance": 10000 }
  ]
}

💡 Notez que les clés ne sont jamais écrites en dur : elles sont lues depuis les variables d'environnement (getenv, process.env, os.environ). Adoptez ce réflexe dès votre premier appel.

4. Base URL

Toutes les requêtes visent la même racine, en HTTPS uniquement :

https://tchin.tech/api/v1

Les chemins documentés (par exemple /payments, /balance) s'ajoutent à cette base : https://tchin.tech/api/v1/payments.

5. Environnements : test & production

L'encaissement dispose d'un mode test (sandbox). Passez "env": "test" à la création d'un paiement pour simuler tout le parcours, sans argent réel. Un compte de test (email, numéro et mot de passe fictifs) est fourni dans votre tableau de bord (menu API → « Compte test ») pour jouer le rôle du client sur la page de paiement.

• env: "test" → aucun argent déplacé, aucun crédit de solde. Idéal pour développer et valider votre intégration. Tchin envoie tout de même un webhook (mode: test).
• env: "live" → paiement réel ; votre solde du pays est crédité après la commission Tchin.

⚠️ Le déboursement (retrait) n'a pas de mode test : il s'effectue toujours en réel et débite votre solde. Testez donc vos retraits avec de petits montants.

6. Convention de réponse

Toutes les réponses sont en JSON et contiennent systématiquement un champ booléen success. C'est le premier champ à contrôler dans votre code, avant de lire le reste :

{ "success": true,  ... }                                // requête réussie
{ "success": false, "message": "Raison de l'erreur" }    // échec métier

En cas d'erreur métier, la réponse porte success: false et un champ message explicatif. Les erreurs de validation (Laravel) renvoient en plus un objet errors détaillant chaque champ. Le détail des codes est décrit sur la page Erreurs & statuts.

7. Montants & devise

• Les montants sont des entiers, exprimés en FCFA — pas de décimales. Exemple : 5000 signifie 5 000 FCFA.
• La devise est le XOF dans la zone UEMOA, et le XAF au Cameroun (même valeur faciale).
• Montant minimum : 100. Montant maximum d'un paiement : 100000000.

8. Sécurité — bonnes pratiques

• Conservez la clé secrète uniquement côté serveur, dans des variables d'environnement — jamais dans le code client, une page web ou une app mobile.
• Ne validez jamais une commande sur le seul retour navigateur du client : celui‑ci peut fermer son onglet. Fiez‑vous au webhook, qui est la source de vérité.
• Authentifiez chaque webhook en recalculant le hash SHA‑512 (voir la page Webhooks).
• Utilisez toujours HTTPS pour vos callback_url et return_url.

9. Démarrage rapide (3 étapes)

1. Créez un paiement — votre serveur appelle POST /api/v1/payments et reçoit une payment_url.
2. Redirigez le client vers cette payment_url : il choisit son pays, son opérateur, et paie sur la page hébergée Tchin.
3. Recevez la confirmation sur votre webhook (callback_url) et marquez la commande comme payée.

→ Continuez avec Encaisser un paiement.

10. Récapitulatif des endpoints

Voici l'ensemble des points d'entrée de l'API. La base est https://tchin.tech/api/v1.

Chaque endpoint est décrit en détail — paramètres, exemples multi‑langages, réponses et notes — dans les pages Encaissement et Retrait / Déboursement.