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
Démarrage rapide
Générer une clé, faire un premier encaissement en 5 min.
Authentification
Headers X-API-Key + X-API-Secret, signature des webhooks.
Sandbox
Tests gratuits avec de faux fonds, isolés de la production.
Encaisser un paiement
Le workflow le plus courant, de bout en bout.
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 :
XOFuniquement. Les montants sont des entiers — le franc CFA n'a pas de subdivision. Un montant décimal est refusé en400. - Numéros : format international sans
+, 12 chiffres :225+ numéro à 10 chiffres (ex.2250701234567). L'opérateur est déduit du préfixe.
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.
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.sk_live_, votre serveur doit être déclaré dans la liste blanche d'IP. Les clés sk_test_ n'ont pas cette contrainte.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" }'
json{ "message": "Transaction acceptée, traitement en cours", "task_id": "a7f8e9c2-1234-4567-89ab-cdef01234567" }
GET /task-status/{task_id}/, ou (recommandé) webhook sur les événements transaction.completed / transaction.failed./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.Environnements
Wakyi expose deux environnements totalement isolés : sandbox pour les tests, production pour le trafic réel.
| Environnement | Description |
|---|---|
| Sandbox | Base 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. |
| Production | Base 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.
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
| Nom | Type | Description |
|---|---|---|
| X-API-Keyrequis | string | Identifiant de votre clé. Format : sk_live_* ou sk_test_*. |
| X-API-Secretrequis | string | Secret associé. Renvoyé une seule fois à la création, jamais consultable ensuite. |
| Content-Typerequis | string | Toujours application/json, sauf pour le téléversement d'un lot (multipart/form-data). |
| Idempotency-Keyoptionnel | string | Obligatoire 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
| Statut | Description |
|---|---|
| 401 Unauthorized | Non authentifié : clé ou secret manquant, invalide ou révoqué. |
| 403 Forbidden | Authentifié 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 Requests | Quota 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.
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.
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.
| Statut | Description |
|---|---|
| 200/202 (replay) | Même clé + même payload : réponse en cache renvoyée, aucune nouvelle écriture. |
| 409 Conflict | Même clé, une requête précédente est toujours en cours de traitement. |
| 422 Unprocessable | Même clé réutilisée avec un payload différent : refus pour éviter l'ambiguïté. |
| 400 Bad Request | En-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.
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" }
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.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
| Code | Description |
|---|---|
| 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
| Statut | Description |
|---|---|
| 400 Bad Request | Montant 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 Conflict | La transaction_reference fournie est déjà utilisée. |
| 502 Bad Gateway | La 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. |
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=.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.
| Nom | Type | Description |
|---|---|---|
| pageoptionnel | integer | Numéro de page, à partir de 1. Un numéro hors bornes renvoie 404 not_found. |
| page_sizeoptionnel | integer | Dé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": [ /* ... */ ] }
200. Vérifiez l'orthographe : les bornes de date se nomment date_from et date_to.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.
| Wallet | Description |
|---|---|
| Mobile Money Collection | Cré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 Credit | Débité par chaque payout B2C. C'est le seul wallet dans lequel un payout peut puiser. |
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.
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_(lessk_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
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 }'
json{ "wallet_id": "5d3f-...", "wallet_type": "Mobile Money Credit", "currency": "XOF", "balance": "500000", "is_test": true }
Numéros de test
| Numéro | Opérateur | Comportement simulé |
|---|---|---|
| 2250700000001 | Orange Money | Succès (Completed) après ~3 s. |
| 2250500000001 | MTN MoMo | Succès (Completed) après ~3 s. |
| 2250100000001 | Moov Money | Succès (Completed) après ~3 s. |
| 2250700000009 | Orange Money | Échec (Failed, « Insufficient funds » côté payeur). |
| 2250500000008 | MTN MoMo | Timeout payeur (Failed / timeout) après 60 s. |
Une fois prêt, basculez simplement vos clés vers sk_live_ : les endpoints sont identiques.
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.
Body
| Nom | Type | Description |
|---|---|---|
| mobile_numberrequis | string | Numéro du payeur, 12 chiffres (225 + 10 chiffres), sans +. L'opérateur est déduit du préfixe. |
| amountrequis | integer | Montant à collecter, en XOF, entier positif. |
| currencyrequis | string | Toujours XOF. Toute autre valeur est refusée en 400. |
| transaction_referenceoptionnel | string | Votre 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. |
| metadataoptionnel | object | Vos é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" } }'
json{ "message": "Transaction acceptée, traitement en cours", "task_id": "a7f8e9c2-..." }
Failed / timeout. Le prompt affiché est celui de l'opérateur ; vous ne le pilotez pas.Payout Mobile Money (B2C)
Effectue un payout depuis votre wallet Mobile Money Credit vers le wallet Mobile Money du bénéficiaire.
Body
| Nom | Type | Description |
|---|---|---|
| mobile_numberrequis | string | Numéro du bénéficiaire, 12 chiffres, sans +. |
| amountrequis | integer | Montant à payer, en XOF, entier positif. |
| currencyrequis | string | Toujours XOF. |
| transaction_referenceoptionnel | string | Votre 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é. |
| metadataoptionnel | object | Mê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" } }'
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.
transaction_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.Suivre un job asynchrone
Retourne l'état d'une tâche asynchrone. Approche polling — alternative aux webhooks, utile en développement.
status: "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.| Statut | Description |
|---|---|
| 404 | Tâche pas encore démarrée (cas normal juste après le POST — réessayez), inconnue, ou résultat expiré (> 24 h). |
| 200 — SUCCESS | La 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 — FAILURE | La 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.
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.
Paramètres de requête
| Nom | Type | Description |
|---|---|---|
| reference | string | Recommandé. Égalité exacte sur votre référence métier. Rend exactement une transaction. |
| task_id | string | Égalité exacte sur le task_id rendu à la création. Votre repli si vous n'avez fourni aucune référence. |
| status | string | Completed, Failed, In Progress, Pending. Insensible à la casse. |
| recipient | string | Correspondance partielle : 0701234567 trouve aussi 2250701234567. |
| search | string | Correspondance partielle sur la référence ou le destinataire. |
| service | string | Mobile Money ou Mobile Money Collection, liste séparée par des virgules. |
| network | string | Orange, MTN, Wave, Moov — liste séparée par des virgules, insensible à la casse. |
| date_from / date_to | string | Bornes AAAA-MM-JJ, incluses. Un date_from postérieur à date_to est refusé en 400. |
| amount_min / amount_max | integer | Bornes de montant, incluses. |
| batch_id | uuid | Toutes les lignes d'un même lot. |
| ordering | string | transaction_date, amount ou status ; préfixe - pour l'ordre décroissant. Défaut -transaction_date. |
| page, page_size | integer | Pagination standard. |
bashcurl "https://api.wakyi.com/api/v1/transactions/?reference=ORDER4821" \ -H "X-API-Key: ..." -H "X-API-Secret: ..."
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" } ] }
reference porte votre valeur, transaction_reference porte la nôtre, et task_id est celle rendue au POST. Rapprochez sur reference.Lister mes wallets
Retourne vos wallets (Mobile Money Credit, Mobile Money Collection) avec leur solde calculé à la demande.
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.
Solde d'un wallet
Retourne le solde d'un wallet précis, identifié par l'id obtenu sur GET /wallet/.
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.
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.
| Nom | Type | Description |
|---|---|---|
| currencyrequis | string | XOF. Vous devez déjà avoir les deux wallets, sinon 404. |
| amountrequis | integer | Montant à 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 }'
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.
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.
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" } ] }
Approuver / refuser un paiement
Rend 202 + task_id : l'envoi part chez l'opérateur ; suivez-le par GET /task-status/ ou attendez le webhook.
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.
| Statut | Description |
|---|---|
| 403 | Pas le droit d'approuver sur ce compte, ou tentative d'approuver un paiement que vous avez vous-même initié. |
| 404 | Cette référence n'est pas sur votre compte. |
| 409 | Le 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.
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}/.
| Nom | Type | Description |
|---|---|---|
| servicerequis | path | mobilemoneyb2c ou mobilemoneyc2b. Sensible à la casse. b2c et c2b seuls ne sont pas valides. |
| filerequis | file | Classeur .xlsx (un .csv est refusé). Maximum 20 Mo. multipart/form-data. |
| currencyrequis | string | XOF, 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"
json{ "message": "Batch enregistré, traitement en cours", "task_id": "3f21c8e0-...", "bulk_id": "5d3f9b12-7c44-4e08-a1f6-92b0c7e5d341", "file_name": "salaires-octobre.xlsx", "total": 142 }
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.
Détail & items d'un lot
Vos lots, du plus récent au plus ancien (tableau JSON nu, non paginé).
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" }
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": "..." } ] }
Annuler un lot
Stoppe le traitement des lignes en attente. Les lignes déjà envoyées (Completed / Failed) ne sont pas modifiées.
json{ "message": "Batch annulé — 57 transaction(s) annulée(s)", "cancelled": 57, "bulk_status": "Cancelled" }
Lister les opérateurs
Retourne la liste des opérateurs supportés et leur état d'activation.
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 } ]
"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).Clés d'API
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" } ]
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.
Crée une nouvelle paire sk_test_ (authentification par le JWT du tableau de bord). Le secret n'est renvoyé qu'une seule fois.
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.
- Vous enregistrez une URL via
POST /webhooks/. - À chaque événement, Wakyi envoie un POST JSON sur cette URL, signé HMAC-SHA256 avec le secret de l'endpoint.
- Répondez
2xxpour accuser réception. Sinon, nous retentons selon l'échéancier ci-dessous. - 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ête | Description |
|---|---|
| X-Webhook-Event | Le type de l'événement (ex. transaction.completed). |
| X-Webhook-Delivery-Id | Identifiant de cette tentative de livraison — un entier rendu en chaîne, identique au champ id de GET /webhooks/{id}/deliveries/. |
| X-Webhook-Signature | Signature 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éponse | Comportement |
|---|---|
| 2xx | Livraison 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. |
Catalogue d'événements
| Événement | Description |
|---|---|
| transaction.completed | Une transaction (C2B, B2C) a abouti. data.object.status = "Completed", error = null. |
| transaction.failed | Une 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 }. |
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.Enregistrer un endpoint
| Nom | Type | Description |
|---|---|---|
| urlrequis | string | URL de votre serveur, 500 caractères max. HTTPS fortement recommandé. |
| eventsoptionnel | array | Types d'événements à recevoir. Omis, l'endpoint est créé mais ne recevra jamais rien. |
| enabledoptionnel | boolean | Dé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"] }'
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" }
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.Gérer un endpoint
Vos endpoints du mode courant (liste paginée), secret masqué.
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.
204. Définitif ; efface aussi l'historique des livraisons. Pour suspendre temporairement sans rien perdre, préférez PATCH { "enabled": false }.
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.
Livraisons & renvoi
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 } ] }
| state | Description |
|---|---|
| PENDING | En attente d'une tentative ; next_attempt_at indique quand. |
| SUCCESS | Votre serveur a répondu 2xx. Terminal. |
| FAILED | Votre serveur a répondu un 4xx autre que 408/429. Terminal : corrigez puis renvoyez. |
| EXHAUSTED | Les 9 tentatives ont été consommées sans 2xx. Terminal, renvoyable. |
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é.