Journal des modifications

Les changements de l’API Monerail, du plus récent au plus ancien.

Les ajouts (nouveaux points d’accès, paramètres facultatifs, champs de réponse, types d’événements, codes d’erreur) peuvent arriver à tout moment. Les changements qui peuvent demander une action de votre part sont marqués Action requise.

2026-10-31 · Nouveaux pays#

Huit pays de plus sont ouverts dans l’API, pour les encaissements et les paiements mobile money : Gabon, Tchad, Congo et Centrafrique (XAF), Mali et Niger (XOF), Guinée (GNF) et RD Congo (CDF).

• Nouvelles devises : GNF (francs entiers) et CDF (en centimes ; envoyez des multiples de 100). Voir Montants et devises.
• country choisit le pays quand une devise est partagée : XAF vaut toujours CM par défaut, XOF vaut SN. Un pays non ouvert pour la devise renvoie 400 country_unsupported.
• Lister les opérateurs accepte un paramètre facultatif country, par exemple GET /v1/operators?currency=XAF&country=TD.
• Codes générés par le client : pour certains opérateurs (Orange Money en Guinée, par exemple), le client compose un code USSD pour obtenir un code de paiement. L’encaissement est requires_otp et next_action.ussd_code contient le code à composer ; transmettez le code de paiement avec authorize.
• next_action.type: "redirect" avec next_action.url peut être renvoyé quand le client valide sur une page de paiement.
• Nouveaux codes d’erreur : country_unsupported, bank_transfer_unsupported (pas de virement bancaire dans ces huit pays), test_phone_required (le mode test n’y accepte que les numéros de test), otp_not_expected.

2026-10-31#

Renforcement de la sécurité et de la fiabilité.

• Action requise. Vérification d’identité : place_of_birth est désormais requis par Envoyer la vérification d’identité. address.postal_code reste facultatif. Limitée à 5 envois par titulaire et par 24 heures. Le rôle de la clé est vérifié avant l’enregistrement de toute pièce.
• Action requise. Les encaissements en NGN échouent désormais avec 400 currency_unsupported. Les paiements et reversements en NGN fonctionnent toujours.
• Action requise. Virements bancaires : recipient.bank_code doit correspondre exactement à un code de Lister les banques. Sinon : 400 bank_account_invalid.
• Action requise. Cartes à usage unique : elles ne peuvent être ni rechargées ni vidées (400 card_single_use), ni avoir de spending_limit (400 parameter_invalid). Une carte à usage unique peut être débitée une fois ; elle est résiliée automatiquement 30 jours après l’émission.
• Action requise. Droits de lecture : lire les événements demande le rôle Propriétaire, Finance ou Développeur ; lire les points de terminaison, Propriétaire ou Développeur. Sinon : 403 permission_denied.
• Limites de débit : 100 requêtes par 10 secondes et par clé d’API, et 10 renvois par événement et par heure. Au-delà : 429 rate_limited avec Retry-After. Voir Limites de débit.
• Actions sur les cartes : quand la réponse de l’émetteur n’est pas définitive, l’émission, la recharge, le retrait, le blocage, le déblocage et la résiliation renvoient 202, et le résultat arrive par webhook. L’argent ne revient au solde cartes qu’une fois l’échec définitif.
• Idempotence : si un problème survient après l’envoi de l’argent à un partenaire, l’API renvoie 202 avec l’objet au lieu d’un 5xx, et une nouvelle tentative avec la même Idempotency-Key le rejoue.
• Points de terminaison : les adresses avec une IP ou utilisateur:mot_de_passe@ sont refusées (400 url_invalid). Les envois vers des domaines qui pointent vers une adresse privée échouent avec « destination not allowed » et sont retentés. Le secret de signature ne figure que dans la réponse 201 d’origine, pas dans les rejeux.
• Encaissements : failure_code vaut désormais failed ou expired ; failure_message peut donner un motif.
• Identité : la vérification est propre à chaque entreprise. Une personne vérifiée par une autre entreprise est vérifiée à nouveau pour la vôtre.
• Erreurs : les requêtes refusées pour une raison sans code propre renvoient un message request_invalid générique, et les erreurs 5xx un message générique. Les refus des partenaires gardent leur motif sous provider_declined.
• Outils de test : Simuler un paiement par carte accepte status: "declined", qui envoie card.authorization_declined sans rien prélever. Simuler une décision de vérification accepte une reason.
• En-têtes : chaque réponse porte Strict-Transport-Security et X-Content-Type-Options: nosniff.
• Données de référence : Lister les opérateurs et Lister les banques sont mis en cache jusqu’à 10 minutes.

2026-10-30#

Première version de l’API Monerail v1 (Monerail-Version: 2026-10-30).

• Solde, encaissements (validation sur le téléphone ou code), paiements vers le mobile money et les comptes bancaires, reversements, transactions.
• Titulaires et vérification d’identité, cartes virtuelles Visa et Mastercard pour les membres de l’équipe, les clients et les agents IA.
• Points de terminaison et événements webhook, signés en HMAC-SHA256 et retentés 8 fois sur environ 42 heures.
• Données de référence (opérateurs, banques), outils de test, clés d’idempotence, pagination par curseur.