Documentation d'intégration — API Marchande Redacok

Version du 08/10/2026. Document public destiné aux développeurs qui intègrent la solution de paiement des applications marchandes Redacok. Il ne contient aucune clé ni information confidentielle.

Adresse de ce document : https://redacok.com/documentation-api (page) et https://redacok.com/documentation-api.md (texte brut Markdown).

URL de base : https://redacok.com/api/applications-marchandes

Cette documentation est complète : en la lisant de bout en bout, vous savez créer une application, encaisser, envoyer de l'argent, suivre vos soldes, comprendre les frais, gérer les erreurs et passer en production.

1. Vue d'ensemble

Une application marchande est créée par un membre de type Établissement, Entreprise, Organisation/Association ou Coopérative, depuis son tableau de bord Redacok (onglet API Marchande). Redacok propose deux familles d'opérations :

Chaque application possède :

La clé secrète est affichée à la création (et consultable tant que l'application est en mode Sandbox). Elle est effacée quand le passage en mode Réel est approuvé : conservez-la dans un coffre de secrets dès sa création. Si vous la perdez ou si elle a pu être exposée, régénérez-en une depuis le tableau de bord (voir partie 11).

2. Démarrage en 7 étapes

1. Créez votre application dans le tableau de bord Redacok (onglet API Marchande) et notez la clé publique, la clé secrète et le secret de webhook.
2. Renseignez l'adresse de votre webhook (https://…) et, si vous le souhaitez, l'e-mail des notifications.
3. Activez, dans le tableau de bord, les moyens de paiement que vous voulez proposer (case par moyen).
4. Faites vos essais en Sandbox (partie 9) : 3 paiements de test réussis sont nécessaires pour demander le passage en Réel.
5. Demandez le passage en Réel depuis le tableau de bord. La demande est validée par la direction de Redacok.
6. Après le passage en production, contactez toujours le support Redacok (messagerie du tableau de bord) pour faire activer, un à un, tous les moyens de paiement dont vous avez besoin, par pays.
7. Mettez à jour vos clés de production sur votre serveur et suivez vos soldes dans le tableau de bord.

3. Conventions générales

• Format : toutes les requêtes sont en JSON (Content-Type: application/json), méthode POST sauf indication contraire.
• Authentification : clePublique et cleSecrete sont envoyées dans le corps JSON de chaque requête (pas d'en-tête Authorization). La consultation d'un statut n'utilise que la clé publique.
• Montant : chaîne de chiffres, jusqu'à 2 décimales ("5000", "1500.50"), strictement positive.
• Devise : XAF par défaut. Une autre devise est convertie en XAF par Redacok ; si votre plateforme convertit déjà, envoyez "XAF". Les soldes et frais sont exprimés en FCFA (XAF).
• Numéro de téléphone Mobile Money : format international, chiffres seulement, sans « + » ni espaces (ex. 237670000000). Pour un numéro camerounais de 9 chiffres commençant par 6, Redacok ajoute l'indicatif 237 si vous l'oubliez. Un numéro invalide est refusé immédiatement par l'opérateur : rien n'est débité.
• Numéro de compte Redacok : le numéro complet du compte (ex. CM10000000010000100000170).
• Erreurs : une réponse HTTP 4xx contient un champ message en français avec la raison (liste complète en partie 12).
• Délai d'attente conseillé pour vos appels : 30 secondes.
• Usage raisonnable : pour suivre un paiement, interrogez le statut toutes les 5 à 10 secondes, pendant 5 minutes au maximum.

4. Recevoir des paiements : POST /paiement/initier

{
  "clePublique": "pk_...",
  "cleSecrete": "sk_...",
  "montant": "5000",
  "devise": "XAF",
  "referenceMarchand": "VOTRE-REFERENCE-UNIQUE",
  "moyenPaiement": "MTN_MOMO",
  "numeroCompteClient": "237670000000",
  "idempotency_key": "cle-unique-optionnelle"
}

Réponse : { "paiementId": "uuid" }. Pour VISA et MASTERCARD, la réponse contient aussi "paymentUrl" : ouvrez ce lien dans le navigateur du client (sur Android, préférez le navigateur du téléphone à une WebView) pour qu'il saisisse sa carte sur la page sécurisée du partenaire de paiement.

Cycle de vie d'un paiement

Chaque paiement est valable 5 minutes, validation chez l'opérateur ou saisie de la carte comprises. Un paiement EXPIRE ne peut plus être validé : créez-en un nouveau.

Comment le client paie selon le moyen

• Mobile Money : le client reçoit une demande de confirmation sur son téléphone et saisit son code secret. Le numéro est vérifié par l'opérateur dès la demande.
• Cartes Visa et Mastercard : le client saisit sa carte sur la page sécurisée (paymentUrl), puis est renvoyé vers votre application.
• `REDACOK_INTERNE` : le client reçoit la demande dans son application Redacok, choisit son compte (Courant ou Épargne) et saisit le code PIN de ce compte.

Retour du client après un paiement par carte

Après la saisie de sa carte, le client est renvoyé vers votre application :

• paiement validé : urlSucces ;
• paiement annulé par le client : urlAnnulation ;
• paiement refusé ou échoué : urlEchec (à défaut, urlAnnulation).

Chaque adresse commence par https:// (ou est le lien d'ouverture de votre application mobile, par exemple monapp://paiement), sans identifiant ni mot de passe, 500 caractères au maximum. Redacok y ajoute les paramètres redacok_paiement (le paiementId), redacok_resultat (succes, annulation ou echec), redacok_statut (statut connu à cet instant) et redacok_reference (votre referenceMarchand). Le paramètre redacok_statut n'est qu'une indication : confirmez toujours le paiement par le webhook ou par la consultation du statut. Sans adresse fournie, le client voit une page de confirmation Redacok neutre.

Consulter un paiement : GET /paiement/{paiementId}/statut?clePublique=pk_...

Réponse : { "statut": "APPROUVE", "montant": "5000.00", "reference": "VOTRE-REFERENCE" }.

Pour les paiements Mobile Money et carte encore EN_ATTENTE, cet appel interroge aussi le partenaire de paiement : c'est le filet de sécurité si un webhook n'arrive pas.

5. Envoyer de l'argent depuis votre wallet

Les trois appels ci-dessous débitent le wallet disponible de l'application (jamais négatif). Mêmes clés dans le corps JSON. Ils servent à payer vos utilisateurs, vendeurs ou livreurs. Les cartes Visa et Mastercard ne s'appliquent pas aux envois.

Moyens d'envoi (`moyenPaiement` de `envoyer-externe`) : MTN_MOMO, ORANGE_MONEY, EXPRESS_UNION, AIRTEL_MONEY, AFRICELL_MONEY, TELMA, LONESTAR_MTN, MOOV_MONEY, MOOV_AFRICA, selon le pays de l'opérateur. Le moyen doit être activé sur votre application (voir partie 7).

Réponses

• verifier-destinataire : { "nomComplet": "Nom du titulaire" }.
• envoyer : { "verdict": "PAIEMENT_ENVOYE", "message": "…", "nomDestinataire": "…" }.
• envoyer-externe : { "verdict": "ENVOI_EFFECTUE", "message": "…" }. Le message contient le montant envoyé, les frais d'envoi éventuels et la référence de l'opérateur.

Comportement

• Le traitement est immédiat : la réponse vous dit tout de suite si l'envoi est parti ou refusé. Il n'y a pas de traitement par lots ni d'horaires imposés par Redacok.
• Si l'opérateur refuse ou n'aboutit pas, le wallet est recrédité intégralement, tout de suite, et l'appel renvoie une erreur.
• Une opération partie ne peut pas être annulée par API. Un envoi n'a que deux issues : ENVOYE (parti) ou refusé (erreur, wallet recrédité).
• Plafonds quotidiens : voir la partie 17.
• Il n'y a pas de webhook pour les envois : la réponse de l'appel fait foi. Retrouvez chaque envoi dans l'historique de votre application (tableau de bord), par l'appel /paiement/historique ou par l'appel /paiement/statut-envoi avec votre referenceMarchand (partie 16).
• Wallet insuffisant : erreur 400 avec le message « Solde du Wallet insuffisant pour cet envoi. » (ou « …pour ce paiement. » pour envoyer). Le montant à couvrir inclut les frais d'envoi si vous les assumez.

6. Wallet, soldes et retraits

• Disponible : argent encaissé en mode Réel, utilisable pour vos envois et vos retraits. Un paiement approuvé en mode Réel est crédité tout de suite (moins les frais si vous les assumez).
• En cours (séquestre) : en mode Sandbox, les montants encaissés restent en séquestre ; ils sont libérés vers le disponible à l'approbation du passage en Réel. En mode Réel, les encaissements d'un moyen de paiement pour lequel Redacok a configuré un délai de disponibilité (par exemple 24 h, 48 h ou plusieurs jours) restent dans le solde « en cours » pendant ce délai, puis passent automatiquement au solde « disponible » (vérification toutes les 10 minutes). Sans délai configuré, l'argent est disponible tout de suite. Le délai dépend du moyen de paiement, du pays et de l'application ; le support vous le communique.
• Consultation : les soldes, l'historique complet des paiements, des envois et des frais se consultent dans le tableau de bord (onglet API Marchande, un bouton par application). Pour votre serveur, trois appels par clés existent : le solde du wallet, l'historique complet et le statut d'un envoi (partie 16). Ils servent à votre rapprochement comptable, en plus de vos webhooks.
• Recharger le wallet : depuis le tableau de bord, transférez des fonds de votre Compte Courant Redacok vers le wallet.
• Retirer vos fonds : depuis le tableau de bord, faites une demande de retrait. Elle est vérifiée puis validée par l'équipe habilitée de Redacok ; vous êtes notifié du résultat.
• Le wallet de chaque application est un compte distinct, séparé des autres wallets et des comptes des clients.

7. Moyens de paiement par pays

Redacok propose les moyens ci-dessous pour les paiements de vos clients. Le pays est celui du marchand (dossier de vérification). À la création de l'application, seul REDACOK_INTERNE est activé ; vous activez ensuite les autres dans le tableau de bord (case par moyen). Après le passage en production, contactez le support Redacok pour faire activer, par pays, tous les moyens dont vous avez besoin. Le support vous confirme en privé les moyens ouverts pour votre application.

Descriptions des moyens : ORANGE_MONEY (Orange Money), MTN_MOMO (MTN Mobile Money), MOOV_MONEY et MOOV_AFRICA (Moov), AIRTEL_MONEY (Airtel Money), AFRICELL_MONEY (Africell), WAVE (Wave), FREE_MONEY (Free Money), T_MONEY (T-Money), MPESA (M-Pesa), TELMA (Telma MVola), LONESTAR_MTN (Lonestar MTN), EXPRESS_UNION (Express Union), VISA et MASTERCARD (cartes bancaires, encaissement uniquement), REDACOK_INTERNE (compte Redacok, encaissement et envoi).

8. Frais

Les frais dépendent du sens (encaissement ou envoi), du pays et du moyen de paiement.

Règle de calcul (identique pour les encaissements et pour les envois) :

1. si des frais ont été configurés sur votre application pour ce moyen et ce sens (pourcentage ou montant fixe, ou « aucun frais »), ce sont ces frais seuls qui s'appliquent ;
2. sinon, ce sont les frais généraux de la plateforme pour ce pays, ce moyen et ce sens (taux du partenaire de paiement + marge de la plateforme + TVA lorsqu'elle s'applique) ; à défaut de ligne pour votre pays, la ligne « tous pays » s'applique.

Le barème applicable à votre application vous est communiqué par le support Redacok et peut être personnalisé pour votre application, séparément pour l'encaissement et pour l'envoi.

Qui assume les frais : réglage « Qui assume les frais » du tableau de bord, par application.

Autres règles :

• Les montants sont à 2 décimales au maximum ; les frais sont arrondis au centième. Les opérateurs travaillent en FCFA entiers.
• Si les frais à la charge du destinataire sont supérieurs ou égaux au montant envoyé, l'envoi est refusé (« Montant trop faible : il ne couvre pas les frais d'envoi. »).
• Il n'y a ni abonnement, ni frais fixe mensuel, ni minimum mensuel pour une application.
• Un paiement refusé, expiré ou un envoi refusé par l'opérateur n'entraîne aucun frais.

9. Mode Sandbox et mode Réel

1. Toute application démarre en Sandbox (essais). Le Sandbox utilise de l'argent réel : chaque transaction de test, entrante ou sortante, est limitée à 200 FCFA (un montant supérieur est refusé).
2. Il faut au moins 3 paiements de test réussis (tous moyens de paiement confondus) pour pouvoir demander le passage en Réel.
3. La demande est validée manuellement par la direction de Redacok. À l'approbation, les fonds de test en séquestre sont libérés vers le wallet disponible.
4. En mode Réel : plus de limite de test (les plafonds des opérateurs et des banques restent applicables), la clé secrète n'est plus consultable (conservez-la) et la liste blanche d'IP (si définie) s'applique à vos appels.
5. Une application en mode Réel ne peut pas revenir en Sandbox. Pour séparer test et production, créez deux applications.
6. Après le passage en Réel, contactez le support pour activer tous les moyens de paiement nécessaires (partie 2, étape 6).

10. Webhooks et idempotence

Webhooks (notification automatique des paiements reçus)

L'URL (obligatoirement en https://) se configure dans le tableau de bord, section de l'application. Une seule adresse par application.

Requête envoyée par Redacok : POST JSON avec les en-têtes X-Redacok-Timestamp (secondes Unix) et X-Redacok-Signature.

{ "paiementId": "uuid", "statut": "APPROUVE", "montant": "5000.00", "applicationId": "uuid" }

statut vaut APPROUVE (payé), REJETE (refusé) ou EXPIRE (paiement non validé dans les 5 minutes). Pour un paiement Mobile Money ou carte que l'opérateur n'a pas encore confirmé, aucun webhook n'est envoyé tant que le résultat n'est pas connu : utilisez la consultation de statut (partie 4).

Vérification de la signature — HMAC-SHA256

signature = HMAC_SHA256( cle = secret_de_webhook,
                         message = timestamp + "." + corps_brut_de_la_requete )

Résultat encodé en hexadécimal minuscule. Utilisez le corps brut exact reçu (pas un JSON reconstruit).

Exemple Node.js (Express) :

const crypto = require('crypto');
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.header('X-Redacok-Timestamp');
  const recu = req.header('X-Redacok-Signature') || '';
  const attendu = crypto.createHmac('sha256', process.env.REDACOK_SECRET_WEBHOOK)
    .update(ts + '.' + req.body.toString('utf8')).digest('hex');
  const ok = recu.length === attendu.length &&
    crypto.timingSafeEqual(Buffer.from(recu), Buffer.from(attendu));
  if (!ok || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);
  const evenement = JSON.parse(req.body.toString('utf8'));
  // traiter evenement.paiementId / evenement.statut (de façon idempotente)
  res.sendStatus(200);
});

Bonnes pratiques :

• rejetez les requêtes dont le timestamp s'écarte de plus de 5 minutes (anti-rejeu, à implémenter de votre côté) ;
• répondez vite (200) : Redacok attend 10 secondes au maximum votre réponse ;
• Renvoi automatique : si votre serveur ne répond pas 2xx dans les 10 secondes (ou est injoignable), Redacok réessaie après 1 minute, 5 minutes, 30 minutes puis 2 heures (5 tentatives au total, chacune re-signée avec un timestamp neuf), puis abandonne. Votre traitement doit donc être idempotent ;
• il n'y a pas de rejeu manuel : la consultation de statut reste votre filet de sécurité ;
• ne marquez une commande comme payée que sur APPROUVE (webhook vérifié ou consultation du statut), jamais sur la seule redirection du navigateur du client.

Idempotence (éviter les doubles opérations)

Pour initier, envoyer et envoyer-externe, envoyez une clé unique par opération (en-tête Idempotency-Key ou champ idempotency_key).

• Même clé et mêmes paramètres : vous recevez le même résultat sans nouvelle opération.
• Même clé avec des paramètres différents : erreur 409.
• Même clé pendant qu'une première requête est encore en cours : erreur 409, réessayez un peu plus tard.

11. Sécurité

• Liste blanche d'IP (optionnelle, mode Réel) : ajoutez l'adresse IPv4 publique de votre serveur dans le tableau de bord (vous pouvez aussi en retirer). Elle s'applique à initier, envoyer et envoyer-externe. Liste vide : aucune restriction. Si elle contient au moins une adresse, tout appel venant d'une autre IP reçoit une erreur 403 : vos appels doivent alors partir d'une IP fixe.
• Rotation des clés : « Régénérer la clé secrète » et « Régénérer le secret de webhook » (tableau de bord) fonctionnent à tout moment, même après le passage en Réel. L'ancienne valeur est invalidée immédiatement : préparez la mise à jour de votre serveur avant de régénérer.
• Gardez la clé secrète côté serveur uniquement.
• Vérifiez toujours la signature des webhooks et le timestamp avant de livrer une commande.
• Redacok contrôle la signature d'un paiement par le PIN du compte du client : vous ne manipulez jamais de code PIN.

12. Erreurs

Une erreur renvoie un code HTTP et un champ message.

13. Questions fréquentes

Faut-il refaire une demande pour chaque moyen de paiement ? Non : activez-les dans le tableau de bord, puis, après le passage en production, demandez au support de confirmer ceux dont vous avez besoin par pays.

Un client peut-il payer deux fois la même référence ? La référence n'est pas imposée unique. Utilisez une clé d'idempotence par opération et gardez votre propre contrôle de doublon sur referenceMarchand.

Que se passe-t-il si le client valide après 5 minutes ? Le paiement est EXPIRE et ne peut plus être validé : créez-en un nouveau. Si un client a été débité chez son opérateur alors que le paiement est expiré, contactez le support avec la référence.

Comment rembourser un client ? Il n'y a pas d'appel de remboursement par API. Contactez le support avec le paiementId : le remboursement est traité par l'équipe habilitée. Vous pouvez aussi renvoyer de l'argent à un compte Redacok avec envoyer, ou à un numéro Mobile Money avec envoyer-externe.

Les paiements par carte passent-ils par 3D Secure ? La saisie de la carte se fait sur la page sécurisée du partenaire de paiement, qui applique ses protections. Pour les litiges de cartes, contactez le support.

Quelles devises ? Vous envoyez en XAF, ou dans une autre devise convertie en XAF par Redacok.

Peut-on utiliser un lien d'application mobile pour le retour de carte ? Oui : monapp://paiement est accepté dans urlSucces, urlAnnulation et urlEchec.

Comment savoir qu'un envoi Mobile Money est bien parti ? La réponse de envoyer-externe le confirme tout de suite (ENVOI_EFFECTUE avec la référence de l'opérateur). En cas d'échec, vous recevez une erreur et le wallet est recrédité.

Où voir mes paiements, envois et frais ? Dans l'historique de chaque application, dans le tableau de bord (onglet API Marchande). Un résumé horaire des opérations vous est aussi envoyé par notification.

Comment connaître mon solde ou rapprocher ma comptabilité ? Par /paiement/solde et /paiement/historique (partie 16), ou dans le tableau de bord.

Comment vérifier un envoi après coup ? Par /paiement/statut-envoi avec votre referenceMarchand (partie 16).

Y a-t-il des limites de montant, des plafonds par jour ou un délai avant que l'argent soit disponible ? Oui, ils sont configurés par Redacok par pays, moyen de paiement et application : voir la partie 17 et la partie 6.

Existe-t-il un environnement de test sans argent réel ? Le Sandbox utilise de l'argent réel, limité à 200 FCFA par transaction.

14. Notifications côté marchand

Chaque application peut avoir sa propre adresse e-mail pour les notifications de transactions (onglet API Marchande). Pour ne pas vous inonder : les 5 premières transactions de chaque heure sont notifiées une par une ; un résumé horaire (nombre et montants reçus, échoués, envoyés, retraits, clients ayant essayé) est ensuite envoyé par notification push.

15. Aide, support et mise en production

Pour toute question d'intégration, pour faire activer un moyen de paiement ou un pays, pour un remboursement, un retrait ou un incident (paiement approuvé mais non crédité, envoi bloqué), contactez le support Redacok depuis votre tableau de bord (espace Messagerie). Indiquez le nom de l'application, le paiementId ou la référence concernée et l'heure approximative.

Après chaque passage en production : contactez le support pour activer tous vos moyens de paiement.

16. Solde, historique et statut d'un envoi par API

Ces trois appels sont destinés à votre serveur (clés dans le corps JSON, mêmes règles que les autres appels : liste blanche d'IP incluse). Aucune clé secrète ne doit être utilisée côté navigateur ou mobile.

POST /paiement/solde — solde du wallet

{ "clePublique": "pk_...", "cleSecrete": "sk_..." }

Réponse : { "disponible": "125000.00", "enCours": "0.00", "devise": "XAF", "mode": "REEL" }. disponible est utilisable pour vos envois et retraits ; enCours est le séquestre du mode Sandbox. Montants en FCFA.

POST /paiement/historique — toutes les opérations

{ "clePublique": "pk_...", "cleSecrete": "sk_...", "sens": "SORTANT", "statut": "ENVOYE", "depuis": "2026-10-01", "jusqua": "2026-10-31", "page": 1, "limite": 50 }

Tous les champs après les clés sont optionnels : sens (ENTRANT pour les paiements reçus, SORTANT pour les envois), statut (EN_ATTENTE, APPROUVE, REJETE, EXPIRE pour les paiements reçus ; ENVOYE, ECHEC pour les envois), depuis et jusqua (dates AAAA-MM-JJ, heure du Cameroun), page (à partir de 1) et limite (50 par défaut, 200 au maximum).

Réponse : { "page": 1, "limite": 50, "total": 132, "operations": [ … ] }, les plus récentes d'abord. Chaque opération contient : id, sens, moyen (moyen de paiement des encaissements), montant, frais, statut, referenceMarchand, destinataire (envois uniquement ; les numéros de téléphone sont masqués sauf les 4 derniers chiffres) et creeLe (date ISO). Utilisez-la pour votre rapprochement comptable. Dans le tableau de bord, l'historique de chaque application affiche les numéros complets (client, destinataire) et permet de rechercher par numéro de téléphone, numéro de compte, nom ou référence, et de filtrer par jour ou par mois.

POST /paiement/statut-envoi — retrouver un envoi

{ "clePublique": "pk_...", "cleSecrete": "sk_...", "referenceMarchand": "VOTRE-REFERENCE" }

Réponse : { "envois": [ { "id": "uuid", "statut": "ENVOYE", "montant": "5000.00", "frais": "0.00", "destinataire": "*****0000", "creeLe": "…" } ] }. Le statut vaut ENVOYE (l'argent est parti) ou ECHEC (refusé par l'opérateur, wallet recrédité). Un envoi refusé avant exécution (clé invalide, solde insuffisant, plafond atteint, montant invalide) n'est pas enregistré : l'appel renvoie alors « Aucun envoi trouvé pour cette référence ». Si votre appel d'envoi a expiré chez vous sans réponse, utilisez cet appel avant de réessayer, ou renvoyez la même clé d'idempotence.

17. Limites, plafonds et délais configurables

Redacok configure, par pays, par moyen de paiement et, si besoin, pour une application précise, les règles suivantes. Elles peuvent être modifiées à tout moment et s'appliquent aux opérations suivantes ; la règle la plus précise l'emporte (application, puis plateforme ; pays, puis tous pays ; moyen précis, puis Mobile Money en général, puis tous les moyens).

Le jour s'entend à l'heure du Cameroun (minuit à minuit). Les montants sont exprimés dans la monnaie du pays concerné.

Valeurs au lancement (modifiables par Redacok, le support vous communique celles qui s'appliquent à votre application) :

• envois vers un numéro Mobile Money : 500 000 par numéro (SIM) et par jour, dans la monnaie du pays (par exemple 500 000 FCFA au Cameroun), quel que soit l'opérateur ;
• envois vers des comptes Redacok : 5 000 000 FCFA par jour et par application en traitement automatique ; au-delà, l'opération doit être vérifiée et les fonds justifiés par le support Redacok.

Quand une règle est dépassée, l'appel est refusé avec un message explicite (« Montant trop faible », « Montant trop élevé », « Plafond atteint »…). Rien n'est alors débité.

Les plafonds propres aux opérateurs et aux banques (encaissements, cartes) s'ajoutent à ceux de Redacok.