Le contrat HTTP de vos paiements, sessions checkout et demandes de retrait.
Origine de l’API : https://api.moneriz.com. Ajoutez les chemins /v1 ci-dessous.
La clé secrète suffit pour le checkout hébergé et Liveframe. Envoyer Authorization: Bearer $MONERIZ_SECRET_KEY depuis votre serveur et Content-Type: application/json sur les POST. Le navigateur reçoit checkoutUrl ou embedUrl, sans clé API. Aucun cookie ni CSRF sur /v1. Le mode et lʼorganisation viennent de la clé, jamais du corps.
La clé publique est facultative : elle permet uniquement GET /v1/payment-methods depuis le navigateur pour une interface personnalisée. La clé secrète peut aussi lire ce catalogue depuis votre serveur. Tous les autres endpoints exigent la clé secrète ; elle ne doit jamais être envoyée au navigateur, publiée dans un dépôt ou transmise à un assistant IA.
Les routes /api du dashboard exigent une session et, pour les écritures, le CSRF. Elles ne sont pas accessibles avec une clé API. Il nʼexiste pas de /v1/payment-links, de liste de sessions, de route publique dʼapprobation de retrait ou de remboursement automatique.
Les montants sont des entiers en XOF, sans décimales. Les dates des réponses sont au format ISO 8601 UTC. Tolérer de nouveaux champs dans les réponses ; les corps POST refusent les champs racine inconnus. Une ressource dʼun autre mode ou dʼune autre organisation répond 404.
Avant tout nouvel encaissement live, lʼidentité de cet espace marchand doit être validée par Moneriz. Un dossier envoyé ou validé dans un autre espace ne suffit pas. Sans validation, les nouvelles clés live, les nouveaux liens ou leur réactivation, les sessions et les charges carte ou Mobile Money sont refusés avec 403 KYB_REQUIRED, y compris avec une ancienne clé. Le mode test reste disponible pour les encaissements ; les contrôles dʼidentité des retraits restent inchangés.
Une révocation conserve les lectures historiques et de statut, les webhooks, la réconciliation et les rejeux qui retrouvent une ressource déjà créée. Elle ne relance ni nʼannule automatiquement les opérations engagées. Le chargement du formulaire carte /stripe-session est bloqué en live sans validation, car il peut reprendre une création incertaine chez Stripe. Une page déjà ouverte chez un prestataire reste suivie jusquʼau résultat.
| Méthode | Chemin | Clé / en-tête | Réponse |
|---|---|---|---|
| POST | /v1/checkout-sessions | Secrète + Idempotency-Key | 201 · checkout_session |
| GET | /v1/checkout-sessions/{id} | Secrète | 200 · checkout_session |
| POST | /v1/payments | Secrète + Idempotency-Key | 201 · payment |
| GET | /v1/payments | Secrète | 200 · liste paginée |
| GET | /v1/payments/{id} | Secrète | 200 · payment |
| GET | /v1/payments/{id}/stripe-session | Secrète | 200 · formulaire carte Stripe |
| GET | /v1/payment-methods | Secrète ou publique (facultative) | 200 · catalogue pay-in |
| GET | /v1/balance | Secrète | 200 · solde |
| POST | /v1/withdrawals | Secrète + Idempotency-Key | 201 · withdrawal pending |
| GET | /v1/withdrawals | Secrète | 200 · liste paginée |
| GET | /v1/withdrawals/{id} | Secrète | 200 · withdrawal |
Idempotency-Key : 16 à 128 caractères, obligatoire sur les trois POST. Générer et enregistrer une clé par opération sur votre serveur avant le premier appel. Son espace est commun à toute lʼorganisation, y compris ses différentes clés API. Utiliser des valeurs distinctes selon le mode et lʼendpoint.
Le rejeu exige le même mode, la même méthode, la même URL et le même JSON. Lʼordre des clés JSON ne compte pas ; celui des tableaux compte. Pendant la fenêtre de cache de 24 heures, une requête différente donne 409 IDEMPOTENCY_KEY_REUSED. Une opération encore en cours donne 409 IDEMPOTENCY_KEY_IN_PROGRESS et Retry-After. Une réponse mémorisée porte Idempotent-Replayed: true.
Le cache des réponses dure 24 heures, y compris les erreurs de validation. La clé reste aussi liée aux paiements, sessions et retraits créés : ne jamais la recycler pour une nouvelle opération après 24 heures. Un rejeu peut renvoyer la réponse initiale, pas le statut actuel ; lire la ressource par GET pour connaître son évolution.
Après un timeout, une coupure, un 5xx ou un résultat ambigu, garder exactement la même clé et le même corps. Un 502 PROVIDER_ERROR peut masquer une charge acceptée : rechercher le paiement par reference si son id est inconnu, attendre le webhook ou contacter le support. Ne pas multiplier les reprises ni changer de clé pour forcer un paiement.
Après un refus de validation certain, corriger la requête et utiliser une nouvelle clé. Après 409 WITHDRAWAL_IN_PROGRESS, traiter la demande existante avant dʼen créer une nouvelle. Un 503 sans ressource durable peut libérer la réservation dʼidempotence ; le client reprend tout de même avec sa clé initiale.
Un refus KYB_REQUIRED peut aussi être mémorisé pendant 24 heures. Après approbation de lʼidentité, utiliser une nouvelle clé uniquement si le refus confirme quʼaucune ressource nʼa été créée. Si une opération existe ou si son issue reste inconnue, reprendre et rapprocher cette même opération avec sa clé initiale.
Quotas par clé et par minute : 120 créations partagées entre paiements et sessions, 600 lectures, 10 créations de retrait. Un plafond supplémentaire de 1 200 requêtes/minute par IP couvre /v1. Les reprises consomment aussi les quotas. Sur 429, respecter Retry-After en secondes et espacer les tentatives.
Conserver X-Request-Id pour le support avec la référence et lʼheure de lʼappel, sans clé ni données sensibles. Les réponses /v1 sont no-store. Une clé publique ne devient jamais secrète grâce à une Idempotency-Key.
POST /v1/checkout-sessions prépare le checkout sans lancer de débit. Les coordonnées et le moyen de paiement sont recueillis ensuite. Ne pas envoyer customer, paymentType ou otp ici.
Une nouvelle session live exige la validation dʼidentité de lʼespace ; sinon 403 KYB_REQUIRED. Réutiliser une session existante ne dispense pas de ce contrôle pour une nouvelle tentative de paiement.
Une référence est unique par organisation et mode. Pour une commande existante, conserver sa session et son Idempotency-Key. Une autre clé sur la même référence donne 409 CHECKOUT_REFERENCE_USED. Si une session expire sans paiement, rapprocher la commande avant de créer une nouvelle intention avec une référence distincte.
| Champ | Règle |
|---|---|
| amount | Obligatoire, entier de 100 à 5 000 000 par défaut (maximum configurable). |
| currency | XOF uniquement, défaut XOF. |
| title / description | Titre obligatoire de 2 à 100 caractères ; description facultative, 500 maximum. |
| reference | Obligatoire, 1 à 100 caractères. |
| country | SN par défaut ; SN, CI, BF, ML, TG ou BJ. Pays initial du checkout. |
| metadata | Objet, défaut {} ; 16 000 caractères JSON maximum ; checkoutSessionId et les noms paymentLink* sont réservés. |
| integrationMode | redirect ou iframe ; préférence dashboard si absent. |
| embedOrigin | Origine exacte déjà autorisée, 300 caractères maximum ; origine par défaut si absent. En iframe, une origine utilisable est obligatoire. |
| successUrl / cancelUrl | 2 048 caractères maximum ; préférences dashboard si absentes, null pour supprimer un retour. HTTPS en live, HTTP localhost/127.0.0.1 possible en test. |
| expiresInMinutes | Entier de 5 à 1 440 ; défaut 30. |
{
"amount": 5000,
"currency": "XOF",
"title": "Accès Pro",
"country": "SN",
"reference": "commande-2026-001",
"metadata": {
"orderId": "commande-2026-001"
},
"integrationMode": "redirect",
"successUrl": "https://app.exemple.com/merci"
}POST /v1/checkout-sessions et GET /v1/checkout-sessions/{id} renvoient id (cs_…), object=checkout_session, mode, status, amount, currency, reference, metadata, integrationMode, checkoutUrl, embedUrl, url, successUrl, cancelUrl, paymentId, paymentStatus, expiresAt et createdAt.
checkoutUrl désigne /payer/{token}. embedUrl désigne /integrer/{token}?parent_origin=… ; une création iframe réussie fournit toujours cette URL, sinon la création est refusée. Elle peut être null en mode redirect. url reprend le parcours choisi. Un token et ses URL donnent accès au checkout : ne pas les indexer ni les publier dans vos journaux publics.
status : open (prêt ou dernière tentative échouée), processing (tentative en cours), complete (payé), expired, disabled ou reversed. paymentId et paymentStatus sont null sans tentative, sinon ils décrivent la dernière tentative. complete correspond au paiement paid ; les deux ressources nʼutilisent pas le même vocabulaire.
Une tentative échouée peut être reprise dans la même session. Une tentative en cours, ambiguë ou expirée ne doit pas être remplacée par une nouvelle charge. Lʼexpiration peut être suivie dʼune confirmation tardive. GET lit la base Moneriz sans appeler Bictorys.
expiresAt limite lʼouverture de nouvelles demandes. Une carte Stripe engagée avant cette date peut maintenir le checkout en processing jusquʼà lʼéchéance effective du Payment : garder le formulaire monté et suivre le statut serveur. La continuation exige la même tentative et une session Stripe existante ; aucune nouvelle charge ne peut démarrer après expiration du checkout.
Les nouvelles cartes passent par Stripe Payment Element dans Moneriz. Mobile Money et les retraits restent chez Bictorys. La carte exige une activation du marchand par l’administration, une configuration Stripe du même mode et un webhook signé opérationnel. GET /v1/payment-methods expose la disponibilité effective ; ne forcez pas un moyen indisponible.
Le parcours recommandé reste POST /v1/checkout-sessions, puis checkoutUrl ou embedUrl : Moneriz charge et confirme le formulaire sécurisé. Une authentification demandée par la banque peut nécessiter une fenêtre ou un retour sur la page Moneriz. Le résultat navigateur et moneriz.payment ne créditent jamais le client ; vérifiez payment.succeeded signé ou GET serveur.
Pour une interface carte personnalisée, après POST /v1/payments avec paymentType=card, nextAction.sessionEndpoint désigne GET /v1/payments/{id}/stripe-session. Votre serveur appelle cette route avec sa clé secrète Moneriz du même marchand et du même mode. Réponse : {publishableKey, clientSecret, sessionId}. Transmettez-la uniquement au client propriétaire de cette commande, sans cache partagé, URL ni journaux. Le secret Stripe sk_ ne quitte jamais Moneriz.
Cette route peut reprendre la création de la même session Stripe après une réponse perdue : ce nʼest pas une simple lecture historique. En live sans identité validée, elle répond 403 KYB_REQUIRED. Continuer à suivre lʼétat du paiement par GET /v1/payments/{id} ou webhook, sans créer une autre demande.
Utilisez Stripe.js et CheckoutElementsProvider de @stripe/react-stripe-js/checkout avec le clientSecret ; PaymentElement affiche les champs et checkout.confirm({redirect:"if_required"}) confirme la même session. Affichez checkout.total.total.amount et recueillez l’email requis. Une carte refusée peut être corrigée dans la même session. Ne créez pas un second paiement après un timeout. Les crédits restent confirmés uniquement côté serveur.
Le clientSecret n’est présent ni dans les listes, ni dans les événements marchands, ni dans les ressources publiques. La route de session exige une clé secrète ; les clés publiques sont refusées. Les paiements déjà ouverts restent suivis après désactivation carte du marchand. Le réglage admin bloque les nouvelles tentatives.
POST /v1/payments lance le parcours prestataire. Préférer les sessions pour utiliser le checkout Moneriz intégré. reference est facultative et nʼest pas une contrainte dʼunicité sur cet endpoint : lʼidempotence repose sur Idempotency-Key.
paymentType est obligatoire sur POST /v1/payments. Sans moyen explicite, la requête est refusée avec PAYMENT_TYPE_NOT_AVAILABLE ; utilisez une session de checkout pour laisser le client choisir. Le catalogue pay-in fournit les couples country/paymentType et les exigences actuelles.
| Champ | Règle |
|---|---|
| amount / currency | Montant obligatoire entier, 100 à 5 000 000 par défaut ; XOF, valeur par défaut. |
| country | SN, CI, BF, ML, TG ou BJ ; déduit du téléphone si absent, sinon SN pour le parcours hébergé/carte. Requis si un moyen direct ne permet pas cette déduction. |
| paymentType | Obligatoire pour créer un paiement ; valeur exacte du catalogue, par exemple wave_money ou card. |
| customer | Objet facultatif : name (1 à 100 caractères), phone (1 à 32, international), email (valide, 254 maximum), country (deux lettres ISO du client). Respecter phoneRequired pour le moyen. |
| otp | 6 à 8 chiffres, seulement lorsque le moyen exige otpRequired ; temporaire, ne pas journaliser ni conserver. |
| reference / description | Facultatives, respectivement 1 à 100 et 1 à 500 caractères. |
| metadata | Objet facultatif ; pas de secrets ni de données de carte. Le corps JSON complet est limité à 1 Mo. |
| successUrl / cancelUrl | URL absolues facultatives, 2 048 caractères maximum ; HTTPS en live, HTTP localhost/127.0.0.1 possible en test. Pas de null ni de préférences dashboard sur cet endpoint. |
{
"amount": 5000,
"currency": "XOF",
"country": "SN",
"paymentType": "wave_money",
"reference": "commande-2026-002",
"customer": {
"name": "Client exemple",
"phone": "+221771234567"
}
}Champs : id (pay_…), object=payment, mode, status, amount, currency, country, paymentType, provider, channel, checkoutUrl, nextAction, confirmation, reference, description, customer, metadata, successUrl, cancelUrl, paymentMeans, failureCode, expiresAt, paidAt et createdAt. customer contient name, phone et email, chacun pouvant être null. Les données absentes comme reference, description, paymentType ou les URL peuvent être null.
status : pending, paid, failed, expired, reversed. confirmation : pending, authorized, confirmed, review. Seul paid confirme un règlement. authorized ne suffit pas ; review demande une vérification. Le statut doit rester le premier contrôle, même si une indication fournisseur subsiste après expiration.
channel vaut hosted ou direct. nextAction vaut {type:"redirect",url}, {type:"ussd",message}, {type:"qr_code",qrCode}, {type:"stripe",sessionEndpoint} ou null. Ne jamais interpréter nextAction=null comme un succès. checkoutUrl peut être null. qrCode est facultatif sur POST et GET unitaire et absent de la liste ; la liste peut néanmoins contenir nextAction.qrCode.
paidAt est null avant confirmation. expiresAt ne prouve pas lʼabsence de débit. failureCode peut coexister avec pending après un incident ambigu. Les statuts lus ne déclenchent ni une charge ni une vérification prestataire.
Le checkout Moneriz affiche déjà les moyens disponibles. Ce catalogue nʼest nécessaire que si vous construisez votre propre interface : clé secrète côté serveur, ou clé publique facultative côté navigateur.
GET /v1/payment-methods renvoie {object:"list",data:[…]}, sans pagination ni filtre serveur par pays. Filtrer data côté client sur country. Chaque entrée contient paymentType, country, available, availability, phoneRequired, otpRequired, channel et qrCode (booléen de capacité). otpInstructions, platformEnabled et unavailableReason peuvent être présents.
availability vaut available, unavailable ou unknown. unknown ne permet pas de présumer quʼun paiement est possible. Une suspension conserve lʼentrée visible avec available=false. unavailableReason peut valoir merchant_disabled, availability_unknown ou platform_disabled.
Ce catalogue concerne les encaissements, pas les payouts. Il nʼexiste pas de catalogue payout public /v1 : ne pas déduire la disponibilité des retraits du pay-in. Le backend contrôle le moyen de retrait avant réservation et à la validation admin.
GET /v1/payments et GET /v1/withdrawals renvoient {object:"list",data:[…],hasMore:boolean,nextCursor:string|null}. Ordre décroissant de création (requestedAt pour les retraits), puis dʼidentifiant. Passer nextCursor comme cursor à lʼappel suivant et conserver les mêmes filtres ; arrêter lorsque hasMore=false.
limit : entier de 1 à 100, défaut 20. cursor : identifiant pay_… ou wd_… obtenu dans la liste. createdAfter : date ISO 8601, filtre strictement après cette date ; fournir UTC pour éviter les ambiguïtés. Le filtre des retraits porte sur requestedAt.
status accepte les statuts de la ressource concernée. Les paiements acceptent aussi reference (1 à 100 caractères, égalité exacte). Une référence peut retrouver plusieurs paiements directs ; rapprocher montant, devise, commande et mode avant toute activation.
Les listes ne constituent pas un instantané figé entre les pages : des insertions ou transitions concurrentes peuvent changer les résultats. Dédoublonner par id pour un export et utiliser les webhooks pour les changements. Il nʼexiste pas de createdBefore, de tri personnalisé ou de pagination des sessions en v1.
GET /v1/balance renvoie currency, available, pendingSettlement, pendingWithdrawals et nextSettlementAt (date ISO ou null), pour lʼorganisation et le mode de la clé. available peut être négatif après une annulation de crédit.
pendingSettlement contient les ventes confirmées qui attendent leur disponibilité : 72 heures en Mobile Money, 14 jours par carte. Ce ne sont pas les paiements clients en cours. pendingWithdrawals contient montant + frais déjà réservés : ils sont déjà retirés du disponible. nextSettlementAt est la prochaine échéance, pas la disponibilité de tout le solde.
Le serveur revérifie le disponible lors de la réservation. Une lecture de solde ne garantit pas quʼune demande ultérieure sera acceptée. La commission des nouveaux paiements est de 5 %, arrondie à lʼentier inférieur ; ne pas recalculer les opérations historiques.
POST /v1/withdrawals réserve amount + fee et renvoie 201 avec status=pending. Aucun transfert ne part avant validation admin, même en test. Une seule demande pending ou processing par propriétaire et mode dans tous ses espaces marchands ; un nouveau clic, une autre clé API ou un autre utilisateur ne contourne pas cette règle.
La clé secrète autorise ce parcours serveur : ne pas envoyer de PIN. Le dashboard exige le PIN personnel. La vérification dʼidentité est requise par défaut pour les deux parcours. Les limites et les suspensions sont revérifiées lors de la validation admin.
Un total comptable réellement négatif dans un espace bloque les nouvelles demandes et approbations du même propriétaire dans ce mode avec NEGATIVE_BALANCE. Les soldes restent séparés, sans compensation automatique entre espaces. Les fonds immatures ou retenus pour risque à total comptable positif ne constituent pas cette dette. Rejouer la demande initiale et suivre un transfert déjà envoyé restent possibles.
Un signal de risque carte ouvert maintient le net restant de son paiement en vérification. Ce net est déjà compris dans pendingSettlement. Les autres fonds disponibles restent utilisables pour un retrait ; une insuffisance de couverture utilise les erreurs habituelles INSUFFICIENT_BALANCE ou NEGATIVE_BALANCE. Ne pas soustraire le net en vérification une seconde fois.
| Champ | Règle |
|---|---|
| amount | Entier obligatoire ; minimum 1 000 XOF par défaut. Maximum, plafond 24 h, délai entre versements et frais dépendent de la configuration serveur. |
| currency | XOF uniquement, valeur par défaut. |
| country | SN, CI, BF, ML, TG ou BJ ; déduit de destination.phone si absent. |
| paymentType | Obligatoire : wave_money, orange_money, mtn_money ou moov. Le couple pays/opérateur doit être disponible pour les payouts. |
| destination | Objet obligatoire : phone international (1 à 32 caractères), name (1 à 100), email facultatif valide (254 maximum). |
| reason | Facultative, 1 à 140 caractères ; défaut « Retrait moneriz ». |
{
"amount": 1000,
"currency": "XOF",
"country": "SN",
"paymentType": "wave_money",
"destination": {
"phone": "+221771234567",
"name": "Marchand exemple"
},
"reason": "Retrait de ventes"
}Champs : id (wd_…), object=withdrawal, mode, status, reviewRequired, amount, fee, currency, country, paymentType, destination {phone,name,email}, reason, simulated, failureCode, providerPayoutId, requestedAt, processedAt et completedAt. Les coordonnées historiques, le motif, le code dʼéchec, la référence prestataire et les dates non encore atteintes peuvent être null.
pending attend lʼadmin ; processing signifie versement engagé et suivi automatiquement chez le prestataire ; completed confirme la fin ; failed ou cancelled libèrent les fonds réservés. reviewRequired=true signale une confirmation absente après une heure ou une date de prise en charge manquante. Le suivi automatique continue ; ce délai ne libère jamais les fonds et nʼautorise pas une nouvelle demande.
Le mode test simule par défaut le transfert après validation admin (simulated=true au résultat) ; il exige toujours un mode sandbox configuré pour /v1. Un test peut aussi être configuré pour appeler le sandbox. Le mode live ne simule jamais.
withdrawal.completed ou withdrawal.failed informe le serveur marchand du résultat final. Un refus admin émet withdrawal.failed avec status=cancelled. Les codes PROVIDER_BALANCE, DESTINATION_LIMIT, PROVIDER_CONFIG et PROVIDER_REJECTED concernent notamment le résultat du versement, pas la preuve quʼun simple timeout a échoué.
Enveloppe : {error:{code,message,param?}}. param est facultatif ; ne pas le supposer présent pour une erreur globale. Traiter code et le statut HTTP, jamais une expression régulière sur le message. Prévoir un repli pour un code futur inconnu.
Les erreurs de saisie ne justifient pas de réessai automatique identique. Les erreurs réseau et prestataire ambiguës exigent de conserver lʼidempotence et de rapprocher le résultat. Ne jamais marquer une commande payée à partir dʼun code HTTP 201 seul.
KYB_REQUIRED est un refus métier : faire valider lʼidentité dans les paramètres de lʼespace concerné, puis reprendre une demande dont lʼissue a été rapprochée. Changer de clé, dʼopérateur ou de parcours ne débloque pas les encaissements live. Les lectures et confirmations dʼopérations existantes ne deviennent pas des échecs financiers.
| HTTP / contexte | Codes | Action |
|---|---|---|
| 401 / 403 | INVALID_API_KEY, SECRET_KEY_REQUIRED | Vérifier clé, révocation, organisation et droit. Garder la clé secrète sur le serveur. |
| 400 (ou 413/415 pour le corps) | VALIDATION_ERROR, AMOUNT_BELOW_MIN, AMOUNT_ABOVE_MAX, COUNTRY_NOT_SUPPORTED, PAYMENT_TYPE_NOT_SUPPORTED, PAYMENT_TYPE_NOT_AVAILABLE, PHONE_REQUIRED, PHONE_INVALID, OTP_REQUIRED | Corriger les champs et relire le catalogue. Corps JSON limité à 1 Mo. |
| 400 · session | EMBED_NOT_CONFIGURED, EMBED_ORIGIN_NOT_ALLOWED, EMBED_ORIGIN_INVALID, INSECURE_URL, INVALID_RETURN_URL | Configurer lʼorigine exacte ou corriger les URL ; error.param désigne embedOrigin, successUrl ou cancelUrl. |
| 400 / 409 · idempotence | IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_KEY_IN_PROGRESS | Fournir une clé valide ; ne pas changer la demande pendant une reprise. IN_PROGRESS : attendre Retry-After. |
| 409 · session | CHECKOUT_REFERENCE_USED | Réutiliser la session de cette commande, sans nouvelle charge. |
| 403 · identité | KYB_REQUIRED | Faire valider le dossier de cet espace avant de nouveaux encaissements live. Ce code protège aussi les retraits lorsque leur politique lʼexige. Ne pas contourner le refus ni abandonner le suivi dʼune opération engagée. |
| 409 · retrait | WITHDRAWAL_IN_PROGRESS, NEGATIVE_BALANCE, INSUFFICIENT_BALANCE, DAILY_LIMIT_EXCEEDED, COOLDOWN_ACTIVE | Traiter le dossier, le retrait existant ou la disponibilité du solde avant une nouvelle demande. |
| 404 | NOT_FOUND | Vérifier identifiant, organisation et mode. |
| 429 | RATE_LIMITED | Attendre Retry-After ; réduire les lectures et regrouper les reprises. |
| 503 | MODE_NOT_CONFIGURED, PAYOUTS_NOT_CONFIGURED, PROVIDER_UNAVAILABLE, CONCURRENT_REQUEST, IDEMPOTENCY_PERSISTENCE_ERROR | Corriger la configuration si nécessaire, puis reprendre avec la même clé et le même corps. |
| 502 / 500 | PROVIDER_ERROR, INTERNAL_ERROR | Résultat potentiellement ambigu : même clé, rapprochement serveur et support si persistant. |
| Résultat de versement | PROVIDER_BALANCE, DESTINATION_LIMIT, PROVIDER_CONFIG, PROVIDER_REJECTED | Vérification admin du prestataire ; aucun rejeu aveugle du payout. |
Tester avec les clés test et votre webhook de test : succès, refus, expiration puis succès tardif, doublon/rejeu de webhook et signature invalide. Vérifier que votre commande nʼest activée quʼune fois, même avec deux onglets ou une fermeture avant le retour.
Tester un timeout et la reprise avec la même Idempotency-Key, un corps modifié, une clé publique sur une route secrète, une ressource dʼun autre mode et les réponses 429/5xx. Ces scénarios peuvent être simulés dans vos tests sans provoquer de débit réel.
Simuler un espace non vérifié ou révoqué : nouvelle clé, lien, réactivation, session, charge live et accès au formulaire carte refusés avec KYB_REQUIRED, même avec une ancienne clé ou une carte déjà activée. Vérifier que le test reste accessible, que lʼapprobation dʼun autre espace ne suffit pas et que les statuts, webhooks et rejeux historiques restent traités. Ne pas provoquer de débit réel pour cette recette.
En iframe : chaque origine autorisée, www et sans www, un domaine refusé, CSP de tous les ancêtres, mobile, redimensionnement à la baisse, QR pending sans navigation et paiement externe dans un nouvel onglet. Le lien de secours réutilise la même session.
Pour les retraits : fonds de moins de 72 h en Mobile Money ou de 14 jours par carte, solde insuffisant, demande déjà active, validation/refus admin et résultat incertain. Ne pas confondre recette sandbox et preuve de disponibilité réelle dans tous les pays. Les payouts incertains et le rapprochement comptable exhaustif nécessitent encore un contrôle opérateur.
Conservez le corps brut avant le parseur JSON. Après vérification, enregistrez l’événement dans une file persistante avant de répondre 2xx, en moins de dix secondes. Le worker doit dédupliquer l’événement et valider la commande, le mode, le montant et la devise avant d’activer le service.
import crypto from 'node:crypto';
const TOLERANCE_MS = 5 * 60 * 1000;
export function verifyMonerizSignature(rawBody: string, secret: string, header: string): boolean {
// 1. Decouper `t=<unix_ms>,v1=<hex>`
let t: string | undefined;
let v1: string | undefined;
for (const part of header.split(',')) {
const separator = part.indexOf('=');
if (separator === -1) continue;
const name = part.slice(0, separator).trim();
const value = part.slice(separator + 1).trim();
if (name === 't') {
if (t !== undefined) return false;
t = value;
}
if (name === 'v1') {
if (v1 !== undefined) return false;
v1 = value;
}
}
if (!t || !/^\d+$/.test(t) || !v1 || !/^[0-9a-f]{64}$/.test(v1)) return false;
// 2. Protection contre le rejeu : fenêtre de 5 minutes
const timestamp = Number(t);
if (!Number.isSafeInteger(timestamp) || Math.abs(Date.now() - timestamp) > TOLERANCE_MS) {
return false;
}
// 3. HMAC sur `${t}.${rawBody}`, avec le t reçu tel quel
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
// 4. Comparaison a temps constant, JAMAIS ===
const received = Buffer.from(v1, 'utf8');
const computed = Buffer.from(expected, 'utf8');
if (received.length !== computed.length) return false;
return crypto.timingSafeEqual(received, computed);
}Les messages peuvent arriver en désordre ou être répétés. Un simple traitement asynchrone en mémoire après la réponse HTTP ne suffit pas. Le guide Markdown ci-dessus rassemble le contrat des événements, les exemples et la référence HTTP.