Documentation de l'API Tchin

Bienvenue 👋. L'API Tchin vous permet d'encaisser des paiements Mobile Money (Orange Money, MTN, Moov, Wave, Yas, Wizall, Djamo, Expresso…) dans 7 pays d'Afrique de l'Ouest et centrale, et de reverser de l'argent à vos clients — le tout depuis votre site web, votre back-office ou votre application mobile, via une seule intégration. Vous n'avez pas à gérer chaque opérateur : Tchin s'en charge.

Sommaire

Encaissement — faire payer vos clients
Retrait / Déboursement — envoyer de l'argent
Webhooks — être notifié des paiements
Erreurs & statuts — codes et dépannage

1. Prérequis

Un compte Tchin vérifié (KYC approuvé) pour passer en production.
Au moins une application créée dans votre tableau de bord (menu API).
Un serveur capable d'envoyer des requêtes HTTPS (PHP, Node, Python, etc.).

2. Obtenir vos clés d'API

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 clés s'affichent :

tchin_pk_… — clé publique (identifie votre application)
tchin_sk_… — clé secrète (à garder côté serveur, jamais dans une page web ni une app mobile)

Vous pouvez créer plusieurs applications (par ex. une par site). Chaque application a ses propres clés et son propre webhook.

3. Authentification

Chaque requête vers l'API doit inclure vos deux clés dans les en-têtes HTTP :

En-têtes HTTP

TCHIN-PUBLIC-KEY: tchin_pk_xxxxxxxxxxxxxxxxxxxxxxxx
TCHIN-PRIVATE-KEY: tchin_sk_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Accept: application/json

Une requête sans clés (ou avec des clés invalides) renvoie 401. Base de l'API : https://tchin.tech/api/v1

4. Environnements : test & production

L'encaissement dispose d'un mode test (sandbox) : passez "env": "test" à la création d'un paiement pour simuler de bout en bout sans argent réel. Un compte de test (email, numéro, mot de passe fictifs) est disponible dans votre tableau de bord (menu API → « Compte test »).

env: "test" → aucun argent, aucun crédit de solde, idéal pour développer.
env: "live" → paiement réel, votre solde est crédité (commission 5%).

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

5. Format des réponses

Toutes les réponses sont en JSON et contiennent toujours un champ success (booléen) :

Convention

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

6. Montants & devise

Les montants sont des entiers en FCFA (XOF) — pas de décimales. Exemple : 5000 = 5 000 FCFA.
Au Cameroun, la devise est le XAF (même valeur faciale).
Montant minimum : 100.

7. Sécurité — bonnes pratiques

Gardez la clé secrète uniquement côté serveur (variables d'environnement).
Ne validez jamais une commande sur le seul retour navigateur : fiez-vous au webhook.
Vérifiez le hash des webhooks (voir la page Webhooks).
Utilisez HTTPS pour vos callback_url et return_url.

8. Démarrage rapide (3 lignes)

Créez un paiement : POST /api/v1/payments → vous recevez une payment_url.
Redirigez le client vers cette URL.
Recevez la confirmation sur votre webhook, et marquez la commande payée.

→ Continuez avec Encaisser un paiement.