Encaisser

Paiement direct

Vous dessinez votre propre écran de paiement et déclenchez le débit vous-même. Le client ne quitte jamais votre site. En échange, c'est à vous d'afficher la liste des opérateurs, de recueillir le numéro et de gérer les trois façons dont un paiement se valide.

Deux appels

1. POST /payments — comme pour la page hébergée, vous obtenez un token. Ignorez la payment_url.
2. POST /payments/{token}/charge — vous envoyez le pays, l'opérateur et le numéro.

Avant tout, récupérez la liste des opérateurs disponibles pour construire votre écran : voir Moyens de paiement.

Déclencher le débit

curl -X POST https://tchin.tech/api/v1/payments/9d3f7a21c4/charge \
  -H "TCHIN-PUBLIC-KEY: tchin_pk_xxxxxxxx" \
  -H "TCHIN-PRIVATE-KEY: tchin_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "country":        "TG",
        "operator":       "t-money-togo",
        "phone":          "90123456",
        "customer_name":  "Awa Diop",
        "customer_email": "awa@example.com"
      }'

Les trois issues possibles

Le champ action vous dit quoi afficher. C'est le cœur de cette intégration : traitez les trois cas ou une partie de vos clients restera bloquée.

confirm_on_phone — la plupart des opérateurs

{
  "success": true,
  "token": "9d3f7a21c4",
  "status": "pending",
  "action": "confirm_on_phone",
  "message": "Une demande de confirmation a été envoyée au 90123456."
}

Une notification est partie sur le téléphone du client. Affichez un écran d'attente et patientez le webhook. Ne bouclez pas sur le statut plus d'une fois toutes les 5 secondes.

redirect — Wave, Djamo, Orange Money Sénégal

{
  "success": true,
  "token": "9d3f7a21c4",
  "status": "pending",
  "action": "redirect",
  "redirect_url": "https://pay.wave.com/c/abc123..."
}

Envoyez le client sur redirect_url. Il valide dans l'application de son opérateur puis revient sur votre return_url.

otp_required — Orange Money Côte d'Ivoire et Burkina

{
  "success": false,
  "token": "9d3f7a21c4",
  "status": "failed",
  "action": "otp_required",
  "message": "Composez #144*82# pour obtenir votre code, puis renvoyez la requête avec le champ otp."
}

Ces opérateurs demandent un code que le client va chercher lui-même : il compose #144*82# en Côte d'Ivoire, *144*4*6*montant# au Burkina. Il ne reçoit rien spontanément — dites-le-lui, sinon il attend un SMS qui n'arrivera jamais. Affichez un champ, puis rappelez /charge avec otp.

Exemple complet

// Côté serveur (Node) — le client ne quitte jamais votre site.
async function debiter(token, { country, operator, phone, otp }) {
  const r = await fetch(`https://tchin.tech/api/v1/payments/${token}/charge`, {
    method: 'POST',
    headers: {
      'TCHIN-PUBLIC-KEY': process.env.TCHIN_PUBLIC_KEY,
      'TCHIN-PRIVATE-KEY': process.env.TCHIN_SECRET_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ country, operator, phone, otp }),
  });
  const d = await r.json();

  switch (d.action) {
    case 'confirm_on_phone':
      return { ecran: 'attente', texte: 'Validez la demande sur votre téléphone.' };

    case 'redirect':
      return { ecran: 'redirection', url: d.redirect_url };

    case 'otp_required':
      // Affichez un champ « code » et rappelez cette fonction avec otp renseigné.
      return { ecran: 'code', texte: d.message };

    default:
      return { ecran: 'erreur', texte: d.message || 'Paiement refusé.' };
  }
}

Les pièges

• Un token, une charge. Créez un nouveau paiement pour chaque tentative sérieuse ; ne rejouez pas un token déjà abouti.
• Vérifiez la disponibilité. /methods renvoie available — c'est le drapeau de l'encaissement, celui qui vous concerne ici. Un opérateur à false doit être grisé, pas proposé. Voir Comment ça marche.
• N'annoncez jamais le succès sur cette réponse. pending veut dire « demande partie ». Le webhook tranche.
• Ne mettez pas vos clés dans la page. Cet appel part de votre serveur ; notre API refuse d'ailleurs les origines extérieures.