Tests

Le mode test en détail : les bacs à sable, les outils de test, les simulateurs du tableau de bord et un scénario complet de carte.

Tout ce qui suit utilise une clé de test (mr_test_…) et ne déplace aucun argent réel. Lisez d’abord Mode test pour comprendre la séparation entre données de test et de production.

Le mobile money en mode test#

Les encaissements et les paiements de test n’atteignent jamais un vrai opérateur ni un vrai portefeuille.

• Dans tous les pays ouverts, le mode test n’accepte que les numéros de test ci-dessous, et le dernier chiffre décide du résultat. Tout autre numéro renvoie 400 test_phone_required. Les erreurs de format (400 phone_invalid) se comportent comme en production.
• Au Cameroun et en Gambie, Monerails simule lui-même l’opération. Dans les autres pays, elle part vers l’environnement de test d’un partenaire de paiement, toujours avec le numéro de test propre à ce partenaire, jamais avec le numéro d’un vrai portefeuille.
• Écrivez votre code pour chaque statut : pending, requires_otp, processing, puis succeeded, failed ou expired. Ne supposez pas qu’un encaissement de test réussit toujours.
• Les encaissements réussis créditent votre solde de test. Servez-vous de ce solde pour essayer les paiements et les reversements.

Numéros de test#

Au Cameroun, en Côte d’Ivoire, au Sénégal, au Bénin, au Togo, au Burkina Faso, au Gabon, au Tchad, au Congo, en Centrafrique, au Mali, au Niger, en Guinée-Bissau, en Guinée, en Gambie et en RD Congo, le mode test n’accepte que ces numéros, pour les encaissements comme pour les paiements. Tout autre numéro renvoie 400 test_phone_required : un test n’atteint jamais un vrai portefeuille.

• Utilisez n’importe quel opérateur renvoyé par Lister les opérateurs pour le pays. Le statut définitif arrive en quelques secondes, par webhook et sur l’objet.
• Un numéro qui finit par 2 n’atteint jamais de statut définitif : il sert à tester les longues attentes.
• Orange Money en Guinée demande un code : l’encaissement est requires_otp. Envoyez n’importe quel code à 6 chiffres avec authorize. 000000, 111111, 222222, 333333 et 444444 font échouer l’encaissement ; tout autre code laisse le numéro décider.

Outils de test des cartes#

Deux points d’accès jouent le rôle de l’émetteur de cartes. Ils demandent une clé de test et le rôle Propriétaire ou Finance.

Les paiements de test sont simulés par Monerails : ils suivent les mêmes règles qu’une vraie autorisation (carte bloquée, solde de la carte insuffisant ou plafond dépassé : paiement refusé, avec ses frais de refus) mais n’atteignent jamais le réseau de cartes. Quand une demande approved est refusée par ces règles, la réponse contient status: "declined", un decline_code (card_frozen, insufficient_funds ou limit_exceeded) et un message.

Limites du mode test#

Les fonds des cartes de test sont partagés par toutes les entreprises de Monerails : le mode test des cartes est donc limité par entreprise.

Au-delà d’une limite, le tableau de bord affiche un message clair et l’API répond 400 test_limit_reached (429 pour le quota mensuel d’émission). Résiliez ou videz les cartes de test inutilisées pour libérer de la place. Une carte de test inutilisée depuis 30 jours, ou toutes les cartes de test d’une entreprise sans activité de test depuis 60 jours, sont vidées vers le solde cartes de test puis résiliées automatiquement. Besoin de plus pour une démonstration ? Contactez-nous.

Un scénario complet de carte#

1. Alimentez le solde cartes de test. Dans le tableau de bord, en mode test, ouvrez Cartes › Recharger le solde cartes, saisissez un montant (de 10 à 100 USD en mode test) et cliquez sur Créditer le solde de test (Propriétaire ou Finance). Le solde de test est crédité immédiatement, sans crypto.
2. Créez un titulaire.

curl https://api.monerails.com/v1/cardholders \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "customer", "first_name": "Awa", "last_name": "Ndiaye", "email": "awa@example.com", "phone": "+237670000999", "country": "CM", "birth_date": "1991-02-03", "id_document": "national_id",
       "documents": { "front": "data:image/jpeg;base64,/9j/4AAQ…", "back": "data:image/jpeg;base64,/9j/4AAQ…" }}'

3. Envoyez la vérification. Les photos de la pièce sont exigées dès la création du titulaire (JPEG ou PNG en base64 : l’API vérifie le format, le poids, 4 Mo chacune, et la résolution, au moins 600 × 400 px) et reprises ici ; renvoyez documents seulement pour les remplacer. verification.status passe à in_review.

curl https://api.monerails.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389/verification \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id_number": "CM12345678",
    "birth_date": "1991-02-03",
    "place_of_birth": "Douala",
    "address": { "line1": "12 rue Joss", "city": "Douala", "state": "Littoral" },
    "documents": { "front": "data:image/jpeg;base64,/9j/4AAQ…", "back": "data:image/jpeg;base64,/9j/4AAQ…" }
  }'

4. Décidez de la vérification. Approuvez-la. Pour tester votre parcours de refus, envoyez "result": "rejected" avec une reason, lisez verification.reason, puis renvoyez la vérification.

curl https://api.monerails.com/v1/test/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389/verification \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"result": "approved"}'

5. Attendez cardholder.kyc_updated avec verification.status à verified, puis émettez une carte. Vous recevez 201 avec une carte active, ou 202 avec une carte pending suivie de card.issued ou card.issue_failed.

curl https://api.monerails.com/v1/cards \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-card-awa-1" \
  -d '{"cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389", "amount": 1000, "label": "Test card"}'

6. Simulez des paiements. Un paiement accepté, puis un refusé. Vérifiez que votre code traite card.transaction et card.authorization_declined, et que le refus n’a rien changé sur la carte.

curl https://api.monerails.com/v1/test/cards/ce2f0aea-7f87-4cbd-8383-03129d1253e0/authorizations \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 400, "merchant": "Notion"}'

curl https://api.monerails.com/v1/test/cards/ce2f0aea-7f87-4cbd-8383-03129d1253e0/authorizations \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 90000, "merchant": "Notion", "status": "declined"}'

7. Gérez la carte. Rechargez-la, videz-la, bloquez-la et débloquez-la. Chaque action peut répondre 202 : traitez le webhook qui suit.
8. Résiliez-la. Résiliez la carte et vérifiez que card.terminated arrive et que son solde est revenu sur le solde cartes (Consulter le solde).

Les simulateurs du tableau de bord#

En mode test, le tableau de bord propose les mêmes simulations derrière des boutons :

Tester vos webhooks#

• Créez un point de terminaison de test : les événements de test ne partent que vers eux, signés avec leur propre secret.
• Pour recevoir les événements sur votre machine, exposez votre serveur local par un tunnel HTTPS doté d’un nom de domaine.
• Pour tester votre vérification de signature sans Monerails, envoyez-vous un événement signé de la même façon (onglet curl de Vérifier la signature).
• Répondez 2xx en moins de 10 secondes, puis essayez une réponse en échec et observez les nouvelles tentatives. Utilisez Renvoyer un événement pour en rejouer un.

Avant la production#

• Chaque statut définitif est traité : encaissements failed et expired, paiements et reversements failed, card.issue_failed, vérifications refusées, paiements par carte refusés.
• Chaque 202 est suivi d’un webhook, jamais d’une seconde création.
• Vos tests échouent s’ils reçoivent "livemode": true.

Suivez ensuite Passer en production.