Journal des modifications

Les changements de l’API Monerails, 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-11-05 · Numéros de test au Cameroun, recherche par référence, clés d’API réaffichables#

• Action requise. Mode test, Cameroun : le mode test n’accepte plus que les numéros de test camerounais (237660000001 réussit, …2 reste pending, …3 échoue). Tout autre numéro renvoie 400 test_phone_required. Les opérations sont simulées par Monerails et n’atteignent jamais un téléphone.
• Lister les encaissements et Lister les paiements acceptent un filtre client_reference, pour retrouver une opération dont la réponse a été perdue. Voir Idempotence.
• Les clés d’API peuvent être réaffichées depuis le tableau de bord après saisie de votre code de double authentification. Les clés créées avant cette date ne le peuvent pas : créez une nouvelle clé et révoquez l’ancienne.

2026-11-04 · Afrique de l’Ouest : nouveaux opérateurs et frais#

• Côte d’Ivoire, Sénégal, Bénin, Togo et Burkina Faso : nouveaux opérateurs Djamo (DJAMO, CI), E-money (EMONEY, SN), Celtiis Cash (CELTIIS) et Coris Money (CORIS, BJ), Wave au Burkina Faso (WAVE). Free Money et TMoney apparaissent désormais sous le nom Mixx by Yas (codes FREE et TMONEY inchangés).
• Dans ces cinq pays, les frais d’encaissement et de paiement dépendent désormais de l’opérateur : voir les Tarifs. Le fee renvoyé sur chaque opération est toujours le montant appliqué.
• Action requise. Les virements bancaires ne sont plus disponibles dans ces cinq pays : payez vers un portefeuille mobile money (un virement bancaire renvoie 400 bank_transfer_unsupported).
• Mode test : ces cinq pays n’acceptent plus que les numéros de test.

2026-11-03 · Bénéficiaires enregistrés#

• Nouvelle ressource Bénéficiaires : créez, listez, consultez, modifiez et supprimez les destinataires que vous payez souvent, avec les mêmes contrôles que les paiements. Ils sont partagés avec le tableau de bord (Paiements › Bénéficiaires), séparés par mode et limités à 500 par mode.
• POST /v1/payouts accepte beneficiary (identifiant d’un bénéficiaire) à la place de recipient ; currency devient alors facultatif. L’objet paiement a un nouveau champ beneficiary.
• Nouveau code d’erreur : 409 beneficiary_exists.

2026-11-03 · Guinée-Bissau et Gambie, nouveaux opérateurs, frais par opérateur#

• La Guinée-Bissau (GW, XOF, Orange Money) et la Gambie (GM, GMD, Afrimoney) sont ouvertes aux encaissements et aux paiements. Les montants en GMD sont en dalasis entiers (multiples de 100 bututs). Des numéros de test sont disponibles pour les deux pays.
• Nouveaux opérateurs : Vodacom en RD Congo (VODACOM) ; Moov Money, Amanata, Nita et Zamani Cash au Niger (MOOV, AMANATA, NITA, ZAMANI). Telecel Money n’est plus proposé en Centrafrique.
• Dans certains pays, les frais d’encaissement et de paiement dépendent désormais de l’opérateur. Le champ fee renvoyé sur chaque encaissement et chaque paiement est toujours le montant appliqué ; voir les tarifs.
• La Zambie et l’Afrique du Sud ne figurent plus parmi les pays en ouverture.

2026-11-03 · Pièce d’identité exigée à la création d’un titulaire#

• Action requise. Créer un titulaire : documents.front est désormais requis, ainsi que documents.back sauf pour un passeport (JPEG ou PNG en base64, mêmes contrôles que la vérification). Absent : 400 parameter_missing ; invalide : 400 document_invalid, avec param indiquant la face.
• Envoyer la vérification d’identité reprend les photos envoyées à la création : documents devient facultatif quand verification.documents_on_file vaut true.
• Cartes : une maintenance mensuelle impayée fait l’objet d’une nouvelle tentative automatique le 15e jour après l’échéance, puis reste en attente jusqu’à la recharge suivante, comme avant.

2026-11-02 · Règles des titulaires alignées sur l’émetteur des cartes#

• Action requise. Créer un titulaire : phone (E.164, longueur contrôlée pour le pays) et birth_date (18 ans ou plus) sont désormais requis ; first_name et last_name acceptent 1 à 50 lettres, espaces, apostrophes, points et traits d’union ; country doit faire partie des pays pris en charge. Nouveaux codes d’erreur : cardholder_underage, country_unsupported, id_document_unsupported.
• Action requise. Envoyer la vérification d’identité : address.state est désormais requis (il ne prend plus la ville par défaut) ; les lignes d’adresse acceptent lettres, chiffres, espaces et , . - uniquement ; les images doivent faire au moins 600 × 400 px. birth_date prend par défaut celle du titulaire. Les refus de l’émetteur renvoient 402 verification_declined ou identity_already_registered.
• Les erreurs de ces points de terminaison nomment toujours le champ dans param (address.line1, documents.back…).

2026-11-02 · Mode test sans argent réel partout#

• Le mode test passe désormais uniquement par les environnements de test de nos partenaires, dans tous les pays : aucune opération de test ne déplace d’argent réel. Le mode test avec argent réel du 2026-10-31 est retiré.
• Au Gabon, au Tchad, au Congo, en Centrafrique, au Mali, au Niger, en Guinée et en RD Congo, utilisez les numéros de test.
• Les codes d’erreur test_amount_limit, test_phone_not_allowed, test_payout_not_allowed et test_quota_exceeded ne sont plus renvoyés.

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. Renouvelez-le avec POST /v1/webhook_endpoints/{id}/rotate_secret : les deux secrets signent les envois pendant le chevauchement (24 heures par défaut).
• 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 Monerails 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.