Documentation développeur

API Wakyi — Paiements Mobile Money en Côte d'Ivoire

L'API Wakyi vous permet d'encaisser (C2B), de payer (B2C) et de suivre vos transactions Mobile Money sur Orange Money, MTN MoMo, Wave et Moov Money, via une seule intégration REST/JSON. Cette documentation couvre les endpoints publics destinés aux intégrateurs B2B : exemples de requête, schémas de réponse et codes d'erreur.

Base URL https://api.wakyi.com/api/v1 Devise XOF Auth X-API-Key + X-API-Secret Webhooks HMAC-SHA256
Démarrage

Bienvenue sur l'API Wakyi

L'API Wakyi vous permet d'orchestrer des paiements Mobile Money B2C et C2B et de gérer vos wallets sur les opérateurs de Côte d'Ivoire. Elle est destinée aux intégrateurs B2B — e-commerce, fintechs, entreprises, institutions — et ne couvre que les endpoints publics destinés aux clients.

Orange Money MTN MoMo Wave Moov Money

Par où commencer

Modèle de l'API

L'API est REST/JSON, versionnée sous /api/v1. Les opérations coûteuses (collecte, payout) sont asynchrones : l'API accuse réception (202), lance un traitement, puis vous notifie via webhook ou polling.

  • Méthodes mutantes : POST, PATCH, DELETE — toujours avec Idempotency-Key.
  • Lectures : GET. Trois listes seulement sont paginées (taille 50, maximum 200) ; voir Pagination & filtres.
  • Fuseau horaire : toutes les dates sont en UTC ISO-8601.
  • Devise : XOF uniquement. Les montants sont des entiers — le franc CFA n'a pas de subdivision. Un montant décimal est refusé en 400.
  • Numéros : format international sans +, 12 chiffres : 225 + numéro à 10 chiffres (ex. 2250701234567). L'opérateur est déduit du préfixe.
Périmètre de cette documentationSeuls les endpoints publics sont décrits ici. Les routes d'administration, les analytiques internes et les callbacks opérateurs ne sont volontairement pas exposés.
Démarrage

Démarrage rapide

Passer de zéro à un premier appel API réussi en 5 minutes : création de clé, encaissement de test, lecture du statut.

Récupérer vos identifiants. Connectez-vous à votre tableau de bord Wakyi et générez une paire de clés : X-API-Key (identifiant public, préfixé sk_live_ en production, sk_test_ en sandbox) et X-API-Secret, affiché une seule fois à la création. Stockez-le dans votre coffre de secrets.
Whitelister votre IP (production seulement). Pour les clés sk_live_, votre serveur doit être déclaré dans la liste blanche d'IP. Les clés sk_test_ n'ont pas cette contrainte.
Faire votre premier appel. Déclencher une collecte de 1 000 XOF vers un numéro Orange Money de test :
bashcurl -X POST https://api.wakyi.com/api/v1/send-mobile-money/c2b \
  -H "X-API-Key: sk_test_xxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: votre_secret_ici" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "mobile_number": "2250700000001",
    "amount": 1000,
    "currency": "XOF",
    "transaction_reference": "TEST0001"
  }'
202 Accepted
json{
  "message": "Transaction acceptée, traitement en cours",
  "task_id": "a7f8e9c2-1234-4567-89ab-cdef01234567"
}
Récupérer le statut. Deux options : polling via GET /task-status/{task_id}/, ou (recommandé) webhook sur les événements transaction.completed / transaction.failed.
À lire avant d'écrire votre boucle de pollingUne réponse acceptée n'est pas un paiement abouti. /task-status/ vous dit où en est le traitement de votre requête ; l'issue réelle est le statut de la transaction (Completed, In Progress, Failed). Ne marquez rien comme payé avant Completed.
Démarrage

Environnements

Wakyi expose deux environnements totalement isolés : sandbox pour les tests, production pour le trafic réel.

EnvironnementDescription
SandboxBase URL https://api.wakyi.com/api/v1 — clés sk_test_*, livemode=false. Aucun appel opérateur réel, faux fonds, simulation de succès/échecs.
ProductionBase URL https://api.wakyi.com/api/v1 — clés sk_live_*, livemode=true. Soumise à la liste blanche d'IP. Tous les débits sont réels.

La base URL est identique ; c'est la clé (et son flag is_test) qui distingue les deux mondes. Vos données sandbox ne polluent jamais vos rapports de production.

Concepts

Authentification

Toutes les requêtes requièrent une paire clé/secret transmise en en-têtes HTTP. Aucune session ni token JWT n'est utilisé.

En-têtes requis

NomTypeDescription
X-API-KeyrequisstringIdentifiant de votre clé. Format : sk_live_* ou sk_test_*.
X-API-SecretrequisstringSecret associé. Renvoyé une seule fois à la création, jamais consultable ensuite.
Content-TyperequisstringToujours application/json, sauf pour le téléversement d'un lot (multipart/form-data).
Idempotency-KeyoptionnelstringObligatoire sur les endpoints de paiement et de transfert (voir Idempotence). Ignoré ailleurs. UUID v4 recommandé.
bashcurl https://api.wakyi.com/api/v1/wallet/ \
  -H "X-API-Key: sk_live_5f3a..." \
  -H "X-API-Secret: wK4n9..."

Réponses d'authentification

StatutDescription
401 UnauthorizedNon authentifié : clé ou secret manquant, invalide ou révoqué.
403 ForbiddenAuthentifié mais interdit : IP source non autorisée (production), service non activé pour le compte, ou clé sans droit de dépense tentant une écriture (code api_key_read_only).
429 Too Many RequestsQuota dépassé. Réessayez avec un backoff exponentiel.

Clés sans droit de dépense

Une clé peut être émise en lecture seule (read_only: true) : elle lit vos données et les exporte, mais ne peut ni les modifier ni engager de fonds. Toute écriture est refusée en 403 api_key_read_only. Son plafond de requêtes est distinct de celui de vos clés de paiement : le trafic d'un tableau de bord ou d'un prestataire ne consomme pas le quota qui sert à payer.

SécuritéNe commitez jamais le secret dans Git et ne l'exposez jamais côté frontend : c'est une clé serveur. Pour une rotation, générez la nouvelle clé, basculez votre intégration, vérifiez que tout le trafic l'utilise, puis révoquez l'ancienne.
Concepts

Liste blanche d'IP

En production, déclarer au moins une adresse IP est obligatoire : sans liste, une clé sk_live_ ne sert à rien. Cette protection ne s'applique pas à la sandbox.

Chaque clé sk_live_* est attachée à une liste d'adresses autorisées, IPv4 ou IPv6, déclarées une par une (pas de plage CIDR, comparaison en égalité stricte). L'IP retenue est celle du dernier maillon de X-Forwarded-For, c'est-à-dire le pair réellement connecté à notre proxy : si un NAT ou un proxy sortant se trouve devant vous, c'est son adresse que nous voyons.

Deux refus, deux gestes

  • Aucune adresse IP autorisée n'est déclarée pour ce compte — votre liste est vide : transmettez-nous vos adresses de sortie.
  • IP non autorisée pour cette clé API — votre liste existe, mais l'appel vient d'ailleurs : il faut y ajouter cette adresse.
Il n'y a pas d'auto-dépannageL'enregistrement n'est pas en libre-service : écrivez à infos@wakyi.com en citant le message de refus. Avant toute migration d'infrastructure (nouveau serveur, nouvelle région cloud, passerelle NAT), envoyez-nous la nouvelle adresse et attendez notre confirmation.
Concepts

Idempotence

Toute requête mutante doit porter un Idempotency-Key. C'est la garantie qu'un retry réseau ne provoquera jamais un double débit.

Vous générez une clé unique (UUID v4 recommandé) pour chaque opération logique. L'API mémorise la réponse pendant 24 h : tout appel ultérieur avec la même clé et le même payload renvoie la réponse en cache, sans rejouer l'opération. La clé est scopée à votre compte.

StatutDescription
200/202 (replay)Même clé + même payload : réponse en cache renvoyée, aucune nouvelle écriture.
409 ConflictMême clé, une requête précédente est toujours en cours de traitement.
422 UnprocessableMême clé réutilisée avec un payload différent : refus pour éviter l'ambiguïté.
400 Bad RequestEn-tête Idempotency-Key manquant sur un endpoint mutant.
bash# Première tentative
curl -X POST .../send-mobile-money/b2c -H "Idempotency-Key: 6fa4..." \
  -d '{"mobile_number":"2250700000001","amount":5000,"currency":"XOF"}'

# Réseau coupé ? Le client retente AVEC LA MÊME CLÉ :
curl -X POST .../send-mobile-money/b2c -H "Idempotency-Key: 6fa4..." \
  -d '{"mobile_number":"2250700000001","amount":5000,"currency":"XOF"}'
# -> renvoie la même réponse, n'envoie pas un deuxième payout

Générez la clé côté client au moment où l'utilisateur final déclenche l'opération, et persistez-la jusqu'à réception de la réponse finale.

Concepts

Approbation des paiements

Sur un compte qui délègue à des sous-utilisateurs, un paiement initié n'est pas envoyé : il attend la validation du titulaire. Sans délégation, rien ne change — vos appels partent immédiatement.

Un sous-utilisateur initie un payout. Les fonds sont immédiatement engagés (ils sortent du solde dépensable), mais rien ne part chez l'opérateur. Le titulaire approuve — l'envoi part alors — ou refuse, et les fonds sont rendus.

Ce que vous recevez à l'initiation

L'appel rend toujours 202. C'est la présence de la clé status qui distingue les deux cas, et c'est le seul point que votre code doit tester :

json// Parti chez l'opérateur — le cas habituel
{ "task_id": "8f3a...", "message": "Payout en cours" }

// EN ATTENTE de validation — aucun task_id
{ "status": "AWAITING_APPROVAL", "reference": "ORDER4821",
  "message": "Payment awaiting approval" }
Pas de task_id tant que ce n'est pas approuvéUn paiement en attente n'a pas de task_id : aucune tâche n'a été lancée. Testez la présence de status avant de lire task_id. Les endpoints de file, d'approbation et de refus sont décrits dans Paiements en attente.
Concepts

Modèle d'erreur

Les refus produits par le cadre applicatif — authentification, autorisation, quota, idempotence, validation — portent une enveloppe structurée. Les refus métier des endpoints de paiement portent une chaîne simple.

Le champ error est toujours présent, mais son type change. Si error est un objet, vous disposez d'un code machine. Si c'est une chaîne, seuls la phrase et le statut HTTP font foi.

json// Forme structurée — erreurs du cadre
{ "error": { "code": "permission_denied",
             "message": "Service 'Mobile Money' non autorisé pour ce compte.",
             "details": null } }

// Forme simple — refus métier des endpoints de paiement
{ "error": "Insufficient balance" }

Codes structurés

CodeDescription
authentication_failed (401)Clé ou secret invalide, clé révoquée, compte désactivé.
not_authenticated (401)Aucun identifiant fourni sur une route protégée.
permission_denied (403)IP hors liste blanche, service non activé, ou ressource appartenant à un autre compte.
api_key_read_only (403)Clé sans droit de dépense tentant une écriture.
throttled (429)Plafond horaire dépassé. Le message indique le délai d'attente.
invalid (400)Validation de schéma (webhooks). details porte le détail champ par champ.
parse_error (400)Corps JSON malformé.
not_found (404)Ressource inexistante, ou numéro de page hors bornes.
idempotency_key_required (400)En-tête Idempotency-Key absent sur un endpoint qui l'exige.
request_in_progress (409)Une requête portant cette même clé est encore en cours.
idempotency_key_payload_mismatch (422)Même clé réutilisée avec un corps différent.
request_failed (500)La requête a échoué après avoir pu engager des fonds. Ne pas rejouer avec la même clé.
request_outcome_unknown (500)Traitement interrompu, issue inconnue. Vérifier l'état avant toute nouvelle tentative.

Refus métier des endpoints de paiement

StatutDescription
400 Bad RequestMontant absent, non entier ou négatif ; champ requis manquant ; numéro mal formé ; opérateur non reconnu ; devise autre que XOF ; solde insuffisant ("Insufficient balance") ; montant hors des bornes de l'opérateur ; transaction_reference trop longue ou au mauvais format.
404 Not Found"Wallet not found" — vous n'avez pas de wallet du type demandé. Une clé sk_test ne voit que les wallets de test.
409 ConflictLa transaction_reference fournie est déjà utilisée.
502 Bad GatewayLa passerelle opérateur n'a pas pu traiter la transaction. Aucun fonds n'est engagé : vous pouvez rejouer, y compris avec la même Idempotency-Key.
Que retenterRetentez sur 429 (avec backoff) et sur 502 (la clé d'idempotence reste valable). Ne retentez pas les autres 4xx sans corriger la requête — et si vous la corrigez, utilisez une nouvelle Idempotency-Key. Sur 500, ne rejouez jamais avant d'avoir vérifié l'état réel via GET /transactions/?reference=.
Concepts

Pagination & filtres

Trois endpoints de liste sont paginés par numéro de page : GET /transactions/, GET /webhooks/ et GET /webhooks/{id}/deliveries/. Les autres listes renvoient un tableau JSON nu.

NomTypeDescription
pageoptionnelintegerNuméro de page, à partir de 1. Un numéro hors bornes renvoie 404 not_found.
page_sizeoptionnelintegerDéfaut 50, maximum 200 (au-delà, ramené à 200 sans erreur).
json{
  "count": 142,
  "next": "https://api.wakyi.com/api/v1/transactions/?page=3",
  "previous": "https://api.wakyi.com/api/v1/transactions/?page=1",
  "results": [ /* ... */ ]
}
Un paramètre inconnu ne provoque pas d'erreurTout paramètre non documenté est ignoré en silence et la liste complète est renvoyée en 200. Vérifiez l'orthographe : les bornes de date se nomment date_from et date_to.
Concepts

Wallets & transferts

Votre compte dispose de deux wallets XOF distincts. L'argent ne passe jamais de l'un à l'autre tout seul : il faut le transférer explicitement avant de pouvoir le dépenser depuis l'autre wallet.

WalletDescription
Mobile Money CollectionCrédité quand une collecte C2B aboutit — l'argent que vous avez encaissé auprès d'un payeur. Ne sert pas directement à financer un payout.
Mobile Money CreditDébité par chaque payout B2C. C'est le seul wallet dans lequel un payout peut puiser.
Le piège : « Insufficient balance » juste après une collecte réussieUne collecte C2B qui aboutit place les fonds dans Mobile Money Collection — pas dans Mobile Money Credit. Si vous tentez ensuite un payout B2C, l'API vérifie le solde de Credit, le trouve inchangé, et renvoie 400 "Insufficient balance". Les fonds existent ; ils sont sur l'autre wallet. Transférez-les d'abord avec POST /transfer-momo-collection-to-momo-credit/.

Le transfert est synchrone (la réponse donne le résultat immédiatement), sans conversion, au sein de votre propre compte uniquement, et exige un Idempotency-Key comme tout endpoint mutant.

Concepts

Sandbox

Un environnement totalement isolé pour tester votre intégration sans dépenser un franc et sans appel opérateur réel.

  • Clés préfixées sk_test_ (les sk_live_ ne fonctionnent pas en sandbox).
  • Aucun appel opérateur réel : un simulateur renvoie des réponses déterministes.
  • Wallets de test isolés, alimentés avec du faux argent (plafond 10 000 000 XOF par wallet).
  • Pas de liste blanche d'IP : n'importe quelle source est acceptée.
  • Tous les événements webhook portent livemode: false.

Créditer un wallet de test

POST/api/v1/test/fund-wallet/

Ajoute de l'argent fictif sur un de vos wallets sandbox ; crée le wallet s'il n'existe pas. Authentification par le JWT du tableau de bord ou par une clé sk_test_ existante.

bashcurl -X POST https://api.wakyi.com/api/v1/test/fund-wallet/ \
  -H "Authorization: Bearer <jwt>" -H "Content-Type: application/json" \
  -d '{ "wallet_type": "Mobile Money Credit", "currency": "XOF", "amount": 500000 }'
200 OK
json{ "wallet_id": "5d3f-...", "wallet_type": "Mobile Money Credit", "currency": "XOF", "balance": "500000", "is_test": true }

Numéros de test

NuméroOpérateurComportement simulé
2250700000001Orange MoneySuccès (Completed) après ~3 s.
2250500000001MTN MoMoSuccès (Completed) après ~3 s.
2250100000001Moov MoneySuccès (Completed) après ~3 s.
2250700000009Orange MoneyÉchec (Failed, « Insufficient funds » côté payeur).
2250500000008MTN MoMoTimeout payeur (Failed / timeout) après 60 s.

Une fois prêt, basculez simplement vos clés vers sk_live_ : les endpoints sont identiques.

Référence API

Collecte Mobile Money (C2B)

Déclenche une demande de paiement vers le wallet Mobile Money du payeur. Le client final reçoit un prompt USSD / notification pour autoriser.

POST/api/v1/send-mobile-money/c2b

Body

NomTypeDescription
mobile_numberrequisstringNuméro du payeur, 12 chiffres (225 + 10 chiffres), sans +. L'opérateur est déduit du préfixe.
amountrequisintegerMontant à collecter, en XOF, entier positif.
currencyrequisstringToujours XOF. Toute autre valeur est refusée en 400.
transaction_referenceoptionnelstringVotre référence métier (numéro de commande, ticket…). Recommandée : c'est la clé sur laquelle vous rapprocherez. Unique ; lettres et chiffres uniquement, 4 à 36 caractères. Omise, nous en générons une.
metadataoptionnelobjectVos étiquettes libres, rendues à l'identique dans GET /transactions/ et dans chaque webhook. 20 clés max (40 caractères, A-Z a-z 0-9 _ -) ; valeurs : chaîne (500 caractères max), nombre, booléen ou null. Ni objet imbriqué, ni tableau. Aucune donnée personnelle : ces valeurs sont stockées et rejouées 24 h dans les livraisons de webhook.
bashcurl -X POST https://api.wakyi.com/api/v1/send-mobile-money/c2b \
  -H "X-API-Key: ..." -H "X-API-Secret: ..." \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{
    "mobile_number": "2250700000001",
    "amount": 2500,
    "currency": "XOF",
    "transaction_reference": "TICKET4421",
    "metadata": { "facture": "INV-2026-0912", "client_id": "CU-4471" }
  }'
202 Accepted
json{ "message": "Transaction acceptée, traitement en cours", "task_id": "a7f8e9c2-..." }
Délai côté payeurLe payeur dispose de 60 secondes pour confirmer le prompt. Passé ce délai, la transaction passe en Failed / timeout. Le prompt affiché est celui de l'opérateur ; vous ne le pilotez pas.
Référence API

Payout Mobile Money (B2C)

Effectue un payout depuis votre wallet Mobile Money Credit vers le wallet Mobile Money du bénéficiaire.

POST/api/v1/send-mobile-money/b2c

Body

NomTypeDescription
mobile_numberrequisstringNuméro du bénéficiaire, 12 chiffres, sans +.
amountrequisintegerMontant à payer, en XOF, entier positif.
currencyrequisstringToujours XOF.
transaction_referenceoptionnelstringVotre référence métier. Unique, lettres et chiffres uniquement, 4 à 36 caractères. Une référence déjà utilisée est refusée en 409, une référence invalide en 400 — dans les deux cas rien n'est débité.
metadataoptionnelobjectMêmes règles que sur le C2B. Jamais transmis à l'opérateur ; n'est pas un critère de recherche.
bashcurl -X POST https://api.wakyi.com/api/v1/send-mobile-money/b2c \
  -H "X-API-Key: ..." -H "X-API-Secret: ..." \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{
    "mobile_number": "2250500000001",
    "amount": 15000,
    "currency": "XOF",
    "transaction_reference": "ORDER4821",
    "metadata": { "facture": "INV-2026-0912", "agent_id": "AG-117" }
  }'
202 Accepted
json{ "task_id": "...", "message": "Payout en cours" }

Pourquoi fournir votre propre référence

Un payout est asynchrone : la réponse 202 ne porte que le task_id, et le statut définitif arrive plus tard. transaction_reference est la clé qui relie cette issue à votre commande : la valeur que vous envoyez ressort sous le nom reference — dans le webhook comme dans GET /transactions/?reference= — et vous la détenez avant même que l'appel ne parte.

Les deux noms ne sont pas symétriquestransaction_reference (ce que vous envoyez) ressort sous reference. La réponse contient par ailleurs un champ nommé transaction_reference : c'est notre identifiant interne, pas le vôtre. Cherchez votre valeur avec ?reference=, jamais avec ?transaction_reference=. Une référence = une transaction ; tout le reste va dans metadata.
Référence API

Suivre un job asynchrone

Retourne l'état d'une tâche asynchrone. Approche polling — alternative aux webhooks, utile en développement.

GET/api/v1/task-status/{task_id}/
status est l'état de la tâche, pas l'issue du paiementstatus: "SUCCESS" signifie « la tâche s'est exécutée sans planter », pas « la transaction a abouti ». Un paiement refusé par l'opérateur rend aussi SUCCESS, avec la clé error dans result. Lisez result, pas status. Une transaction In Progress n'est pas livrée : attendez Completed via GET /transactions/?reference= ou le webhook.
StatutDescription
404Tâche pas encore démarrée (cas normal juste après le POST — réessayez), inconnue, ou résultat expiré (> 24 h).
200 — SUCCESSLa tâche s'est exécutée. Lire result : result.error présent = refusé ; result.success présent = accepté, pas encore nécessairement livré.
200 — FAILURELa tâche elle-même a échoué (panne de notre côté) ; error porte le détail.
json{
  "task_id": "a7f8e9c2-1234-4567-89ab-cdef01234567",
  "status": "SUCCESS",
  "result": { "success": "Payment request sent", "mobile_number": "2250700000001", "originatingID": "ORDER4821" },
  "error": null
}

Backoff conseillé : 2 s, puis 5 s, puis 10 s. Traitez les premiers 404 comme « pas encore prête » ; n'abandonnez qu'après environ 60 s sans transition.

Référence API

Lister les transactions

Retourne vos transactions paginées, et permet de retrouver une transaction précise par sa référence ou son task_id.

GET/api/v1/transactions/

Paramètres de requête

NomTypeDescription
referencestringRecommandé. Égalité exacte sur votre référence métier. Rend exactement une transaction.
task_idstringÉgalité exacte sur le task_id rendu à la création. Votre repli si vous n'avez fourni aucune référence.
statusstringCompleted, Failed, In Progress, Pending. Insensible à la casse.
recipientstringCorrespondance partielle : 0701234567 trouve aussi 2250701234567.
searchstringCorrespondance partielle sur la référence ou le destinataire.
servicestringMobile Money ou Mobile Money Collection, liste séparée par des virgules.
networkstringOrange, MTN, Wave, Moov — liste séparée par des virgules, insensible à la casse.
date_from / date_tostringBornes AAAA-MM-JJ, incluses. Un date_from postérieur à date_to est refusé en 400.
amount_min / amount_maxintegerBornes de montant, incluses.
batch_iduuidToutes les lignes d'un même lot.
orderingstringtransaction_date, amount ou status ; préfixe - pour l'ordre décroissant. Défaut -transaction_date.
page, page_sizeintegerPagination standard.
bashcurl "https://api.wakyi.com/api/v1/transactions/?reference=ORDER4821" \
  -H "X-API-Key: ..." -H "X-API-Secret: ..."
200 OK
json{
  "count": 1, "next": null, "previous": null,
  "results": [ {
    "id": 9821,
    "reference": "ORDER4821",
    "transaction_reference": "bb774629-81b2-4964-9278-f5041cf25f1c",
    "task_id": "b8dfa889-39db-47e7-b4fc-040d0e3eaa05",
    "service": "Mobile Money",
    "network": "MTN",
    "currency": "XOF",
    "amount": "15000",
    "actual_amount": "15000",
    "status": "Completed",
    "error": null,
    "recipient": "2250500000001",
    "metadata": { "facture": "INV-2026-0912" },
    "transaction_date": "2026-10-23T06:03:21Z"
  } ]
}
Trois identifiants dans un même payloadreference porte votre valeur, transaction_reference porte la nôtre, et task_id est celle rendue au POST. Rapprochez sur reference.
Référence API

Lister mes wallets

Retourne vos wallets (Mobile Money Credit, Mobile Money Collection) avec leur solde calculé à la demande.

GET/api/v1/wallet/
200 OK
json[
  { "id": "5d3f9b12-7c44-4e08-a1f6-92b0c7e5d341", "currency": "XOF",
    "wallet_type": "Mobile Money Credit", "balance": 1250000,
    "created_at": "2026-10-11T09:24:07.512Z" }
]

balance est un nombre JSON, pas une chaîne. Le solde est calculé depuis le journal des transactions et inclut les débits encore In Progress : c'est le solde dépensable. Une clé sk_test ne rend que vos wallets de sandbox. Cette liste n'est pas paginée.

Référence API

Solde d'un wallet

Retourne le solde d'un wallet précis, identifié par l'id obtenu sur GET /wallet/.

GET/api/v1/wallet-balance/{wallet_id}
200 OK
json{ "wallet_id": "5d3f9b12-...", "wallet_type": "Mobile Money Credit", "wallet_currency": "XOF", "balance": 1250000 }

Cette route s'écrit sans slash final ; un slash de fin donne un 404. 404 : wallet inconnu ou de l'autre mode ; 403 : wallet d'un autre compte. La devise se lit sous wallet_currency.

Référence API

Transfert Collection → Credit

Déplace des fonds de votre wallet Mobile Money Collection vers votre wallet Mobile Money Credit, sans conversion, au sein de votre propre compte. C'est l'endpoint qu'il vous faut juste après une collecte C2B, avant un payout B2C avec le même argent.

POST/api/v1/transfer-momo-collection-to-momo-credit/
NomTypeDescription
currencyrequisstringXOF. Vous devez déjà avoir les deux wallets, sinon 404.
amountrequisintegerMontant à déplacer, entier positif.
bashcurl -X POST https://api.wakyi.com/api/v1/transfer-momo-collection-to-momo-credit/ \
  -H "X-API-Key: ..." -H "X-API-Secret: ..." -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{ "currency": "XOF", "amount": 100000 }'
200 OK
json{
  "message": "Transfert effectué avec succès.",
  "details": { "sender_balance_before": 370000, "sender_balance_after": 270000,
               "receiver_balance_before": 0, "receiver_balance_after": 100000 }
}

400 : devise ou montant manquant / non positif, ou solde insuffisant dans Collection. 404 : l'un des deux wallets n'existe pas. Les messages d'erreur de cet endpoint sont en français.

Référence API

Paiements en attente

Liste les paiements initiés par un sous-utilisateur et en attente de décision du titulaire. Un compte sans délégation reçoit 200 avec count: 0, jamais un refus.

GET/api/v1/payments/pending/
200 OK
json{ "count": 1, "results": [
  { "reference": "ORDER4821", "status": "AWAITING_APPROVAL",
    "amount": "15150", "actual_amount": "15000", "currency": "XOF",
    "service": "Mobile Money", "network": "MTN", "recipient": "2250500000001",
    "initiated_by": "agent-abidjan", "initiated_at": "2026-10-23T10:00:00Z" }
] }
Référence API

Approuver / refuser un paiement

POST/api/v1/payments/{reference}/approve/

Rend 202 + task_id : l'envoi part chez l'opérateur ; suivez-le par GET /task-status/ ou attendez le webhook.

POST/api/v1/payments/{reference}/reject/
bashcurl -X POST "https://api.wakyi.com/api/v1/payments/ORDER4821/reject/" \
  -H "X-API-Key: ..." -H "X-API-Secret: ..." -H "Content-Type: application/json" \
  -d '{ "reason": "Bénéficiaire incorrect" }'

Le motif est obligatoire (400 sinon). La transaction passe à Failed et les fonds engagés redeviennent dépensables ; aucune écriture compensatoire n'est créée. Le motif ressort dans le champ error du webhook : n'y mettez rien de confidentiel.

StatutDescription
403Pas le droit d'approuver sur ce compte, ou tentative d'approuver un paiement que vous avez vous-même initié.
404Cette référence n'est pas sur votre compte.
409Le paiement n'attend plus de décision : quelqu'un a tranché entre-temps. Rechargez la file.

Ces deux endpoints n'exigent pas d'Idempotency-Key : une seconde approbation rend 409, le verrou suffit.

Référence API

Lancer un lot (Excel)

Téléverse un classeur .xlsx contenant des paiements en masse. Chaque ligne est traitée indépendamment. Réponse immédiate avec un bulk_id ; le suivi se fait sur GET /bulk-batches/{bulk_id}/.

POST/api/v1/bulk-upload/{service}/
NomTypeDescription
servicerequispathmobilemoneyb2c ou mobilemoneyc2b. Sensible à la casse. b2c et c2b seuls ne sont pas valides.
filerequisfileClasseur .xlsx (un .csv est refusé). Maximum 20 Mo. multipart/form-data.
currencyrequisstringXOF, appliquée à toutes les lignes.

Format du fichier

Première ligne = en-tête, noms de colonnes en MAJUSCULES : NUMBER (numéro du destinataire, 12 chiffres sans +), AMOUNT (entier, sans séparateur de milliers). Une colonne NETWORK est acceptée mais ignorée : l'opérateur est toujours déduit du numéro.

bashcurl -X POST https://api.wakyi.com/api/v1/bulk-upload/mobilemoneyb2c/ \
  -H "X-API-Key: ..." -H "X-API-Secret: ..." -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@salaires-octobre.xlsx" -F "currency=XOF"
202 Accepted
json{ "message": "Batch enregistré, traitement en cours", "task_id": "3f21c8e0-...",
  "bulk_id": "5d3f9b12-7c44-4e08-a1f6-92b0c7e5d341", "file_name": "salaires-octobre.xlsx", "total": 142 }
Arrêt sur fonds épuisésSi le solde est épuisé en cours de lot, les lignes suivantes ne sont pas tentées : elles passent en FAILURE avec error_code: "NOT_ATTEMPTED". Le task_id rendu ici est celui du répartiteur, pas d'une transaction : suivez le lot par bulk_id.

Cycle de vie — lot : Pending → Processing → Completed | Partially failed | Failed | Cancelled. Ligne : QUEUED → PROCESSING → SUCCESS | FAILURE | CANCELLED. Codes d'erreur par ligne (contractuels) : INSUFFICIENT_FUNDS, NOT_ATTEMPTED, UNKNOWN_OPERATOR, AMOUNT_OUT_OF_BOUNDS, WALLET_NOT_FOUND, UNSUPPORTED_SERVICE, TECHNICAL.

Référence API

Détail & items d'un lot

GET/api/v1/bulk-batches/

Vos lots, du plus récent au plus ancien (tableau JSON nu, non paginé).

GET/api/v1/bulk-batches/{bulk_id}/
200 OK
json{ "id": "5d3f9b12-...", "service_type": "mobilemoneyb2c", "status": "Processing", "currency": "XOF",
  "file_name": "20261023100000_salaires-octobre.xlsx", "total_items": 142,
  "success_count": 84, "failure_count": 1, "queued_count": 57, "processing_count": 0, "cancelled_count": 0,
  "created_at": "2026-10-23T10:00:00Z" }
GET/api/v1/bulk-batches/{bulk_id}/items/?status=FAILURE

Lignes individuelles avec le statut de chacune. Filtre status : QUEUED, PROCESSING, SUCCESS, FAILURE, CANCELLED. Branchez votre traitement sur error_code, contractuel ; error est un message libre.

json{ "bulk_id": "5d3f9b12-...", "total": 142, "success": 140, "failure": 2, "queued": 0,
  "items": [ { "number": "2250900000001", "amount": "25000", "status": "FAILURE",
              "error_code": "UNKNOWN_OPERATOR", "error": "..." } ] }
Référence API

Annuler un lot

Stoppe le traitement des lignes en attente. Les lignes déjà envoyées (Completed / Failed) ne sont pas modifiées.

POST/api/v1/bulk-batches/{bulk_id}/cancel/
200 OK
json{ "message": "Batch annulé — 57 transaction(s) annulée(s)", "cancelled": 57, "bulk_status": "Cancelled" }
Référence API

Lister les opérateurs

Retourne la liste des opérateurs supportés et leur état d'activation.

GET/api/v1/telecom-operators/
200 OK
json[
  { "id": 1, "network_name": "orange", "mobile_money_operator_id": "orange_money", "prefixes": ["07"], "is_enabled": true, "network_down": false },
  { "id": 2, "network_name": "mtn",    "mobile_money_operator_id": "mtn_momo",     "prefixes": ["05"], "is_enabled": true, "network_down": false },
  { "id": 3, "network_name": "moov",   "mobile_money_operator_id": "moov_money",   "prefixes": ["01"], "is_enabled": true, "network_down": false },
  { "id": 4, "network_name": "wave",   "mobile_money_operator_id": "wave",         "prefixes": ["01","05","07"], "is_enabled": true, "network_down": false }
]
Wave n'est pas lié à un préfixeUn wallet Wave peut exister sur n'importe quel numéro ivoirien. Pour router vers Wave plutôt que vers l'opérateur du préfixe, passez "network": "wave" explicitement dans le corps du C2B / B2C. Sans ce champ, le routage suit le préfixe (07 → Orange Money, 05 → MTN MoMo, 01 → Moov Money).
Référence API

Clés d'API

GET/api/v1/api-keys/{user_id}/

Retourne toutes les clés actives du compte ; les secrets ne sont jamais renvoyés. Le mode se lit au préfixe (sk_live_ / sk_test_), la portée au champ read_only, et label est le nom donné à la création.

json[ { "key": "sk_live_a7f8...", "revoked": false, "created": "2026-10-12T08:33:00Z", "read_only": false, "label": "Backend prod" } ]
POST/api/v1/api-keys/revoke/{user_id}/{api_key_value}/

Désactive immédiatement et irréversiblement une clé ; toute requête la portant renvoie 401 à partir de cet appel. Générez la clé de remplacement avant de révoquer l'ancienne.

POST/api/v1/test/keys/

Crée une nouvelle paire sk_test_ (authentification par le JWT du tableau de bord). Le secret n'est renvoyé qu'une seule fois.

Webhooks

Concept & signature

Recevez les changements de statut de vos transactions en push sur l'URL HTTPS de votre choix. Plus efficace que le polling, recommandé en production.

  1. Vous enregistrez une URL via POST /webhooks/.
  2. À chaque événement, Wakyi envoie un POST JSON sur cette URL, signé HMAC-SHA256 avec le secret de l'endpoint.
  3. Répondez 2xx pour accuser réception. Sinon, nous retentons selon l'échéancier ci-dessous.
  4. Les événements sandbox (livemode: false) et production (livemode: true) sont envoyés sur des endpoints séparés.

En-têtes de la requête

En-têteDescription
X-Webhook-EventLe type de l'événement (ex. transaction.completed).
X-Webhook-Delivery-IdIdentifiant de cette tentative de livraison — un entier rendu en chaîne, identique au champ id de GET /webhooks/{id}/deliveries/.
X-Webhook-SignatureSignature au format t=<timestamp>,v1=<hmac>. Pas d'en-tête de timestamp séparé.
httpPOST /votre-url HTTP/1.1
Content-Type: application/json
X-Webhook-Event: transaction.completed
X-Webhook-Delivery-Id: 4213
X-Webhook-Signature: t=1761213600,v1=5257a869e7a...

{
  "id": "evt_79d9f944cbf0432ba9d2a6f8",
  "type": "transaction.completed",
  "created": 1761213600,
  "livemode": false,
  "data": { "object": {
    "id": 10042,
    "transaction_reference": "9f1c2b7a-0000-4e00-8000-0000000000aa",
    "reference": "TICKET4421",
    "service": "Mobile Money Collection",
    "network": "Orange",
    "currency": "XOF",
    "amount": "2500",
    "actual_amount": "2500",
    "status": "Completed",
    "error": null,
    "recipient": "2250700000001",
    "metadata": { "facture": "INV-2026-0912" },
    "transaction_date": "2026-10-23T10:13:57.939015Z"
  } }
}

Vérifier la signature

La signature est HMAC-SHA256(timestamp + "." + corps_brut, secret). Vérifiez sur les octets bruts reçus, pas sur un JSON re-sérialisé ; validez que le timestamp est récent (< 5 min) pour rejeter les replays ; comparez en temps constant.

javascriptconst crypto = require('crypto');
// Express : app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }))
function verify(req, secret) {
  const header = req.headers['x-webhook-signature'] || '';
  const ts  = header.match(/t=([^,]+)/)?.[1];
  const sig = header.match(/v1=([0-9a-f]+)/)?.[1];
  if (!ts || !sig) return false;
  const expected = crypto.createHmac('sha256', secret)
    .update(ts + '.' + req.rawBody.toString('utf8')).digest('hex');
  return sig.length === expected.length &&
         crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Nouvelles tentatives

Votre réponseComportement
2xxLivraison acquittée. Aucune nouvelle tentative.
5xx, 408, 429, timeoutÉchec temporaire : 9 tentatives au total sur ~20 h (+5 s, +30 s, +5 min, +30 min, +2 h, +6 h, +12 h…).
Autres 4xxÉchec définitif dès la première tentative : nous considérons que votre endpoint nous refuse. Corrigez puis renvoyez la livraison.
Webhooks

Catalogue d'événements

ÉvénementDescription
transaction.completedUne transaction (C2B, B2C) a abouti. data.object.status = "Completed", error = null.
transaction.failedUne transaction a échoué. status = "Failed" et error contient la raison (message opérateur ou motif de refus).
webhook.testÉvénement synthétique pour tester votre endpoint (via POST /webhooks/{id}/test/). data.object = { message, endpoint_id }.
Pas de webhook intermédiaireAucun webhook n'est émis pour l'état In Progress. Vous n'êtes notifié qu'à l'état final. Recommandations : répondre en moins de 5 s et traiter en asynchrone ; brancher votre logique sur le champ type ; stocker id (evt_…) pour dédupliquer en cas de retry ; logger le payload intégral.
Webhooks

Enregistrer un endpoint

POST/api/v1/webhooks/
NomTypeDescription
urlrequisstringURL de votre serveur, 500 caractères max. HTTPS fortement recommandé.
eventsoptionnelarrayTypes d'événements à recevoir. Omis, l'endpoint est créé mais ne recevra jamais rien.
enabledoptionnelbooleanDéfaut true. false suspend les livraisons sans supprimer l'endpoint.

Le mode test/live est déduit de la clé utilisée et ressort en lecture seule sous is_test.

bashcurl -X POST https://api.wakyi.com/api/v1/webhooks/ \
  -H "X-API-Key: ..." -H "X-API-Secret: ..." -H "Content-Type: application/json" \
  -d '{ "url": "https://app.exemple.ci/hooks/wakyi", "events": ["transaction.completed", "transaction.failed"] }'
201 Created
json{ "id": 7, "url": "https://app.exemple.ci/hooks/wakyi", "events": ["transaction.completed", "transaction.failed"],
  "enabled": true, "is_test": false, "secret": "whsec_Zx8Qq1r7Vn3s...", "created_at": "2026-10-23T10:31:00.412907Z" }
Le secret n'est rendu qu'une fois, et ne peut pas être tournéStockez secret maintenant ; les lectures ultérieures n'en renvoient qu'une empreinte masquée. Pour changer de secret : supprimer l'endpoint et en créer un nouveau. Prévoyez d'accepter temporairement deux secrets pendant une bascule.
Webhooks

Gérer un endpoint

GET/api/v1/webhooks/

Vos endpoints du mode courant (liste paginée), secret masqué.

PATCH/api/v1/webhooks/{id}/

Met à jour url, events (remplace la liste — ce n'est pas un ajout) ou enabled. id, is_test, secret et created_at sont en lecture seule.

DELETE/api/v1/webhooks/{id}/

204. Définitif ; efface aussi l'historique des livraisons. Pour suspendre temporairement sans rien perdre, préférez PATCH { "enabled": false }.

POST/api/v1/webhooks/{id}/test/

Met en file un événement webhook.test (202 + delivery_id). Le 202 n'est pas un accusé de réception : relisez les livraisons pour le verdict.

Webhooks

Livraisons & renvoi

GET/api/v1/webhooks/{id}/deliveries/

Livraisons de cet endpoint, les plus récentes d'abord, avec leur état, le nombre de tentatives et le dernier code HTTP reçu. Paginé.

json{ "count": 23, "results": [
  { "id": 41827, "event_type": "transaction.completed", "event_id": "evt_79d9f944cbf0432ba9d2a6f8",
    "target_url": "https://app.exemple.ci/hooks/wakyi", "state": "SUCCESS", "attempts": 1, "response_status": 200,
    "last_attempt_at": "2026-10-23T10:31:01.884210Z", "next_attempt_at": null } ] }
stateDescription
PENDINGEn attente d'une tentative ; next_attempt_at indique quand.
SUCCESSVotre serveur a répondu 2xx. Terminal.
FAILEDVotre serveur a répondu un 4xx autre que 408/429. Terminal : corrigez puis renvoyez.
EXHAUSTEDLes 9 tentatives ont été consommées sans 2xx. Terminal, renvoyable.
POST/api/v1/webhooks/{id}/deliveries/{delivery_id}/resend/

Rejoue une livraison passée en conservant son event_id (votre déduplication sur id continue de s'appliquer) ; attempts repart à 0 et le calendrier de réessai du début. 409 si la livraison est encore PENDING ou si un renvoi a eu lieu il y a moins d'une minute ; 404 si elle n'appartient pas à cet endpoint ou n'est pas dans le mode de votre clé.

Besoin d'aide ?Accès sandbox, liste blanche d'IP, questions d'intégration : infos@wakyi.com.