Démarrer

Comment ça marche

Avant d'écrire la moindre ligne, cinq choses à comprendre. Elles expliquent la plupart des surprises rencontrées en intégration : un opérateur qui refuse un virement tout en acceptant les paiements, un solde qui semble bloqué dans le mauvais pays, un versement qui met une heure à se conclure. Rien ici n'est un détail technique : c'est ce qui décide de ce que vous affichez à vos clients.

1 · Deux mouvements, jamais à confondre

Encaisser, c'est prendre de l'argent chez un client : il valide sur son téléphone, la somme arrive sur votre solde. Décaisser, c'est l'inverse : vous envoyez de l'argent depuis votre solde vers un numéro mobile money.

Ces deux mouvements empruntent des chemins différents chez les opérateurs. Ils ont leurs propres tarifs, leurs propres délais et — c'est le point suivant — ils tombent en panne séparément.

2 · Un réseau a deux canaux indépendants

Orange Money Burkina peut très bien encaisser normalement pendant que ses virements sortants sont coupés. Ce n'est pas une hypothèse d'école : c'est arrivé, et l'argent d'un transfert est resté immobilisé chez nous une journée avant d'être rendu à son expéditeur.

La liste des moyens renvoie donc deux disponibilités, jamais une seule :

{
  "code": "orange-money-burkina",
  "name": "Orange Money",

  "available":        true,    // vos clients PEUVENT payer avec ce réseau
  "payout_available": false    // mais vous NE POUVEZ PAS y envoyer d'argent
}

curl -H "TCHIN-PUBLIC-KEY: tchin_pk_xxxxxxxx" \
     -H "TCHIN-PRIVATE-KEY: tchin_sk_xxxxxxxx" \
  https://tchin.tech/api/v1/methods

Nous interrogeons chaque réseau toutes les minutes, sans déplacer un franc, et ces deux drapeaux suivent le résultat. Quand un canal se rétablit, il redevient disponible tout seul : vous n'avez rien à redéployer.

Deux filtres évitent de trier vous-même : ?for=payout ne renvoie que les réseaux qui acceptent un virement, ?for=subscription que ceux qui se prélèvent sans le client devant l'écran. Sans filtre, vous avez tout. Détail complet : Moyens de paiement.

3 · Un solde par pays — mais ils se partagent

Votre argent n'est pas dans un pot commun : vous avez un solde par pays, alimenté par ce que vous y encaissez. Un paiement reçu au Togo crédite votre solde Togo, parce que c'est l'opérateur togolais qui détient les fonds.

Les 6 pays de l'UEMOA — Sénégal, Côte d’Ivoire, Bénin, Burkina Faso, Togo et Mali — partagent la même monnaie. Si vous demandez un décaissement au Togo et que le solde Togo ne suffit pas, nous allons chercher le complément sur vos autres soldes de cette zone avant de conclure au refus. Vous n'avez rien à demander : cela se fait dans l'appel lui-même.

Le Cameroun reste à part : le franc CFA d'Afrique centrale n'est pas celui de l'UEMOA, et les deux ne se convertissent pas entre eux. Un solde camerounais ne sert qu'au Cameroun.

Chaque rapatriement apparaît dans votre historique comme une ligne de transfert distincte, et la réponse de l'API vous dit ce qui a bougé — pour que ces lignes ne vous surprennent pas :

{
  "success": true,
  "disburse_token": "dsb_7f21ac93",
  "country": "TG",
  "amount":  10000,
  "fee":     340,
  "debited": 10340,

  // Présents seulement si nous avons puisé dans vos autres soldes.
  "rebalanced":    ["CI → TG : 6 000 FCFA"],
  "rebalance_fee": 91
}

Si même en réunissant toute la zone le compte n'y est pas, l'appel est refusé et rien n'est débité. Voir Décaissement et Solde.

4 · Rien n'est instantané, et c'est normal

Un paiement mobile money passe par le réseau de l'opérateur. Le client doit valider sur son téléphone, souvent en moins d'une minute ; s'il hésite, la demande expire. Un taux d'échec élevé n'est pas le signe d'un problème chez vous : c'est la norme du mobile money.

• Ne concluez jamais depuis votre écran. La réponse à un appel dit « la demande est partie », pas « l'argent est arrivé ». Seul le webhook signé, ou l'appel au statut, fait foi.
• Un paiement pending n'est pas un paiement perdu. Nous relisons son état réel auprès de l'opérateur et vous renotifions dès qu'il bouge.
• Une opération non aboutie ne débite personne. Elle est enregistrée pour la traçabilité, rien de plus.
• Un webhook peut arriver deux fois. Le champ token est votre clé d'idempotence : traitez-le une seule fois.

5 · Ce qui se passe quand ça coince

Un décaissement que l'opérateur finit par refuser vous est intégralement recrédité, frais compris. Nous interrogeons l'opérateur toutes les deux minutes sur tout versement resté en attente, nous finalisons ou nous vous remboursons, et nous vous envoyons le webhook. Vous n'avez rien à surveiller — vous le pouvez, mais ce n'est pas à vous de le faire.

L'argent revient sur le solde du pays visé, pas sur celui d'où il était parti. Si nous avions rapatrié depuis un pays voisin pour couvrir la somme, ce mouvement-là reste fait : votre argent a simplement changé de pays, et les frais de rapatriement restent acquis parce que le virement bancaire, lui, a bien eu lieu.

Un encaissement qui n'aboutit pas, lui, ne débite personne : il n'y a rien à rembourser.

Et nous vous prévenons. Dès qu'un réseau tombe, un message part vers les comptes vérifiés, en précisant lequel des deux canaux est touché et ce que ça change pour vous. Un second message annonce le rétablissement.

Et maintenant

Vous en savez assez pour intégrer sans mauvaise surprise. La suite dépend de ce que vous voulez faire :

• Encaisser avec notre page de paiement — une requête, nous affichons l'écran et gérons les trois façons de valider.
• Encaisser sur votre propre écran — le client ne quitte jamais votre site.
• Prélever tous les mois — sans le client devant l'écran.
• Envoyer de l'argent — vers un numéro mobile money.
• Comprendre un statut ou une erreur — quand quelque chose ne se passe pas comme prévu.