Décaisser

Envoyer de l'argent

Payer un vendeur, rembourser un client, verser une commission : vous envoyez de l'argent de votre solde Tchin vers un numéro mobile money. Deux appels — on prépare, puis on confirme.

Le solde d'un seul pays ne vous bloque pas

Vous avez un solde par pays, mais les six pays de l'UEMOA 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 pendant l'appel à initiate.

Nous puisons d'abord dans les soldes les mieux garnis, pour faire le moins de mouvements possible. Le Cameroun reste isolé : son franc CFA n'est pas celui de l'UEMOA, et les deux ne se convertissent pas.

Si même en réunissant toute la zone le compte n'y est pas, l'appel est refusé — voir Solde insuffisant plus bas. Ce qui avait déjà été rapatrié reste sur le pays visé : c'est votre argent, il a simplement changé de pays.

1 · Préparer

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": "90123456",
        "amount":        10000,
        "withdraw_mode": "t-money-togo",
        "callback_url":  "https://votre-site.com/webhook/tchin"
      }'

Réponse

{
  "success": true,
  "disburse_token": "dsb_7f21ac93",
  "country": "TG",
  "amount":  10000,   // ce que le destinataire reçoit
  "fee":     340,     // frais Tchin
  "debited": 10340,   // ce qui quitte votre solde

  // Présents seulement si nous avons dû puiser dans vos autres soldes
  // de la même zone monétaire pour couvrir la somme.
  "rebalanced":    ["CI → TG : 6 000 FCFA"],
  "rebalance_fee": 91
}

Rien n'est parti à ce stade. Vous pouvez montrer fee et debited à votre utilisateur avant qu'il confirme.

Solde insuffisant

Renvoyé seulement quand la zone entière n'y suffit pas. available_zone vous dit ce que vous pourriez réunir au total, frais de rapatriement déduits — c'est le plafond honnête à afficher à votre utilisateur.

{
  "success": false,
  "message": "Solde insuffisant sur le pays TG.",
  "balance":   8000,    // le solde du pays visé, après renfort
  "required": 10340,
  "fee":        340,

  // Ce que vous pourriez réunir en tout sur la zone, frais déduits.
  "available_zone": 9100,
  // Ce que nous avons déjà rapatrié avant de renoncer.
  "rebalanced": ["ML → TG : 1 100 FCFA"]
}

2 · Confirmer

curl -X POST https://tchin.tech/api/v1/disburse/submit \
  -H "TCHIN-PUBLIC-KEY: tchin_pk_xxxxxxxx" \
  -H "TCHIN-PRIVATE-KEY: tchin_sk_xxxxxxxx" \
  -d '{"disburse_token":"dsb_7f21ac93"}'

{ "success": true, "status": "success", "message": "Déboursement réussi.", "transaction_id": "…" }

// ou, si l'opérateur prend son temps :
{ "success": true, "status": "pending", "message": "Déboursement en cours, vérifiez le statut." }

success signifie que l'argent est parti. pending signifie que l'opérateur traite encore : ne renvoyez pas la requête, interrogez le statut.

3 · Suivre

Un déboursement resté en attente est vérifié automatiquement toutes les deux minutes de notre côté : nous interrogeons l'opérateur, finalisons ou remboursons votre solde, et vous renvoyons le webhook. Vous n'avez pas à surveiller vous-même, mais vous le pouvez.

Être prévenu du résultat

Un décaissement ne se conclut pas toujours dans la seconde. Plutôt que d'interroger le statut en boucle, donnez-nous une adresse : nous vous appelons dès qu'il est réglé, dans un sens ou dans l'autre.

• Le callback_url de la requête, s'il est présent.
• Sinon, le webhook enregistré sur votre application, dans votre espace Tchin.

La notification a la même forme et la même signature que celle d'un encaissement — vérifiez-la de la même façon, voir Webhooks & signature. Un champ kind à "payout" la distingue ; status vaut completed ou failed.

Exemple complet

<?php
// Payer un vendeur : initier puis soumettre. Deux appels, toujours dans cet ordre.
function envoyerArgent(string $numero, int $montant, string $operateur): array
{
    $init = appelTchin('POST', '/disburse/initiate', [
        'account_alias' => $numero,
        'amount'        => $montant,      // ce que le destinataire reçoit
        'withdraw_mode' => $operateur,
        'callback_url'  => 'https://votre-site.com/webhook/tchin',
    ]);

    if (empty($init['success'])) {
        // Solde insuffisant : $init['required'] vous dit combien il faut.
        throw new RuntimeException($init['message']);
    }

    // Rien n'est encore parti : c'est « submit » qui déclenche le virement.
    return appelTchin('POST', '/disburse/submit', [
        'disburse_token' => $init['disburse_token'],
    ]);
}

Ce qu'il faut savoir

• Minimum 200 FCFA. En dessous, l'opérateur refuse.
• Un déboursement n'est pas annulable. Vérifiez le numéro avant de confirmer : il n'existe pas de retour en arrière.
• Le pays vient de l'opérateur. moov-benin débite votre solde Bénin — et, s'il ne suffit pas, vos autres soldes de la zone viennent en renfort au tarif du transfert.
• Vérifiez payout_available avant de proposer un opérateur. Un réseau peut encaisser normalement et refuser les versements : /methods?for=payout ne renvoie que ceux qui versent en ce moment.
• Échec = remboursement intégral. Si l'opérateur refuse, votre solde est recrédité du montant et des frais, sur le pays visé. Nos frais ne se prennent que sur un versement qui aboutit.
• Idempotence. Soumettre deux fois le même disburse_token ne paie pas deux fois.