Reverser de l'argent (retrait / déboursement)
Le déboursement vous permet d'envoyer de l'argent à vos clients (Orange Money, Wave, MTN, Moov, Yas…) depuis votre solde Tchin. Il se déroule en deux temps : initier la demande, puis la soumettre pour exécution. Vous pouvez ensuite vérifier le statut.
⚠️ Pas de mode test — le déboursement est toujours réel. Assurez-vous d'avoir le solde nécessaire avant d'initier.
Prérequis
- Compte vérifié et application API active.
- Un solde suffisant dans le pays correspondant au moyen choisi.
- L'API de déboursement activée sur votre compte (contactez-nous si besoin).
Règle importante : le solde par pays
Le débit est effectué sur le solde du pays correspondant au moyen de paiement. Par exemple, un retrait via t-money-togo ou moov-togo débite uniquement votre solde Togo. Si ce solde est insuffisant, la requête est refusée (400) et vos soldes des autres pays ne sont pas touchés.
Étape 1 — Initier
POST /api/v1/disburse/initiate
| Champ | Type | Requis | Description |
|---|---|---|---|
account_alias | texte | oui | Numéro du bénéficiaire, sans indicatif pays. |
amount | entier | oui | Montant en XOF (pas de décimales). |
withdraw_mode | texte | oui | Le moyen de paiement (voir la liste plus bas). |
callback_url | URL | recommandé | URL où renvoyer les détails de la transaction. |
curl -X POST https://tchin.tech/api/v1/disburse/initiate \
-H "TCHIN-PUBLIC-KEY: tchin_pk_xxxxxxxx" \
-H "TCHIN-PRIVATE-KEY: tchin_sk_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"account_alias": "771111111",
"amount": 4500,
"withdraw_mode": "orange-money-senegal",
"callback_url": "https://monsite.com/retrait/callback"
}'{ "success": true, "disburse_token": "hwTHAS0WvTmTaYT2zDoO", "country": "SN" }Le disburse_token renvoyé sert à soumettre puis à vérifier. À ce stade, le statut interne est created (rien n'est encore débité).
Étape 2 — Soumettre
POST /api/v1/disburse/submit — corps : { "disburse_token": "…" }
curl -X POST https://tchin.tech/api/v1/disburse/submit \
-H "TCHIN-PUBLIC-KEY: tchin_pk_xxxxxxxx" \
-H "TCHIN-PRIVATE-KEY: tchin_sk_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "disburse_token": "hwTHAS0WvTmTaYT2zDoO" }'Réponse en cas de succès :
{
"success": true,
"status": "success",
"message": "Success! Amount of 4500 FCFA transferred to ...",
"transaction_id": "TFA-TX-37XqPpVCjU7ReiycUg97"
}Réponse en cas de traitement asynchrone (certains opérateurs) :
{ "success": true, "status": "pending", "message": "Déboursement en cours, vérifiez le statut." }C'est à la réussite que votre solde du pays est débité (une seule fois, de façon idempotente).
Étape 3 — Vérifier le statut
POST /api/v1/disburse/status — corps : { "disburse_token": "…" }
curl -X POST https://tchin.tech/api/v1/disburse/status \
-H "TCHIN-PUBLIC-KEY: tchin_pk_xxxxxxxx" \
-H "TCHIN-PRIVATE-KEY: tchin_sk_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "disburse_token": "hwTHAS0WvTmTaYT2zDoO" }'Statuts possibles
| Statut | Signification |
|---|---|
created | Demande créée, pas encore soumise. |
pending | Soumise, en cours chez l'opérateur. Vérifiez le statut plus tard. |
success | Transfert abouti. Solde débité. |
failed | Échec. Aucun débit. Vous pouvez recommencer. |
Exemple PHP complet
<?php
function tchin_post($path, $body) {
$ch = curl_init('https://tchin.tech/api/v1/'.$path);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'TCHIN-PUBLIC-KEY: '.getenv('TCHIN_PUBLIC_KEY'),
'TCHIN-PRIVATE-KEY: '.getenv('TCHIN_SECRET_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($body),
]);
return json_decode(curl_exec($ch), true);
}
// 1) Initier
$init = tchin_post('disburse/initiate', [
'account_alias' => '771111111', // numéro du bénéficiaire, SANS indicatif
'amount' => 4500,
'withdraw_mode' => 'orange-money-senegal',
'callback_url' => 'https://monsite.com/retrait/callback',
]);
if (!empty($init['success'])) {
// 2) Soumettre pour exécution
$res = tchin_post('disburse/submit', ['disburse_token' => $init['disburse_token']]);
if (($res['status'] ?? '') === 'pending') {
// 3) Vérifier plus tard le statut final
$final = tchin_post('disburse/status', ['disburse_token' => $init['disburse_token']]);
}
}Liste des withdraw_mode
| Pays | withdraw_mode |
|---|---|
| 🇸🇳 Sénégal | orange-money-senegal, free-money-senegal, expresso-senegal, wave-senegal, djamo-sn |
| 🇨🇮 Côte d'Ivoire | orange-money-ci, mtn-ci, moov-ci, wave-ci, djamo-ci |
| 🇧🇯 Bénin | mtn-benin, moov-benin |
| 🇧🇫 Burkina Faso | orange-money-burkina, moov-burkina-faso |
| 🇹🇬 Togo | t-money-togo, moov-togo |
| 🇲🇱 Mali | orange-money-mali |
| 🇨🇲 Cameroun | mtn-cameroun |
Bonnes pratiques
- Vérifiez votre solde avant d'initier pour éviter les refus.
- Sur
pending, interrogez le statut périodiquement jusqu'au statut final. - Conservez le
disburse_tokenet letransaction_idpour le rapprochement comptable. - Voir les codes d'erreur sur la page Erreurs & statuts.