Cartes

Émettez des cartes virtuelles Visa et Mastercard pour votre équipe, vos clients ou vos agents IA.

Monerails émet des cartes virtuelles en dollars, par l’intermédiaire d’un établissement partenaire réglementé. Elles fonctionnent en ligne partout où Visa ou Mastercard est accepté.

L’argent#

Les cartes puisent dans votre solde cartes, en dollars, distinct de vos soldes en devises africaines. Alimentez-le depuis le tableau de bord en stablecoins (voir Recharger en crypto). Chaque carte a ensuite son propre solde : vous la rechargez depuis le solde cartes et pouvez y rapatrier l’argent à tout moment. Lisez les deux soldes avec Consulter le solde.

Recharger en crypto#

Les recharges se font uniquement depuis le tableau de bord (aucun endpoint d’API), par un Propriétaire ou un membre Finance, une fois votre entreprise vérifiée pour la production.

1. Ouvrez Cartes › Recharger le solde cartes.
2. Choisissez le montant en dollars (de 10 $ à 10 000 $ par recharge) et l’actif et le réseau : USDT ou USDC sur TRON (TRC20), BNB Smart Chain (BEP20), Polygon, Solana ou Ethereum (ERC20).
3. Cliquez sur Générer l’adresse de dépôt. Chaque recharge a sa propre adresse, le montant exact de jetons à envoyer et une heure d’expiration.
4. Envoyez ce montant exact, uniquement sur le réseau choisi, en un seul virement, avant l’expiration.

Une fois le paiement confirmé sur le réseau, le solde cartes est crédité du montant demandé, moins les frais de recharge affichés avant la génération de l’adresse. Vous recevez un e-mail et un événement cards_balance.credited, et la recharge apparaît dans vos transactions. Une recharge n’est créditée qu’une seule fois, quel que soit le nombre de notifications reçues.

Si le paiement ne correspond pas à la demande (montant insuffisant ou excédentaire, autre jeton ou autre réseau, paiement après l’expiration), rien n’est crédité automatiquement : l’équipe Monerails vérifie le paiement et crédite la valeur réellement reçue, puis vous êtes prévenu. Ne réutilisez jamais une ancienne adresse de dépôt : générez-en une nouvelle pour chaque recharge.

En mode test, il n’y a pas d’adresse : saisissez le montant et cliquez sur Créditer le solde de test. Le solde cartes de test est crédité immédiatement, sans crypto.

1. Créer le 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,…", "back": "data:image/jpeg;base64,…" }
  }'

type vaut team pour votre équipe et customer pour vos clients. Les titulaires n’ont pas accès à votre tableau de bord.

La photo de la pièce d’identité est obligatoire dès la création : documents.front, et documents.back sauf pour un passeport (JPEG ou PNG, base64 ou URI data:, 4 Mo au plus, au moins 600 × 400 px). Absente : 400 parameter_missing ; illisible, trop lourde ou trop petite : 400 document_invalid, avec param indiquant la face. Les photos sont contrôlées avant la création du titulaire et reprises par la vérification (verification.documents_on_file: true).

L’émetteur des cartes contrôle chaque champ : l’API applique donc ses règles avant tout envoi (sinon 400 avec param) :

2. Vérifier son identité#

L’émetteur doit vérifier chaque titulaire. Envoyez la vérification avec les informations de la pièce. Les photos envoyées à la création sont reprises ; ajoutez documents seulement pour les remplacer :

{
  "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,…", "back": "data:image/jpeg;base64,…" }
}

• Le prénom, le nom et la date de naissance doivent correspondre exactement à la pièce.
• Les photos doivent être nettes, non recadrées et sans reflet, pièce entière visible. Pour un passeport, envoyez seulement le recto.
• place_of_birth, address.city et address.state : 2 à 60 caractères, sans chiffres. address.line1 (requis) et address.line2 : lettres, chiffres, espaces et , . - uniquement. address.postal_code est facultatif (1 à 10 caractères) : omettez-le s’il n’en existe pas.
• Images : JPEG ou PNG, 4 Mo au plus, au moins 600 × 400 px. documents.back est requis sauf pour un passeport. Sinon 400 document_invalid ou parameter_missing, param indiquant la face.
• Si l’émetteur refuse l’envoi lui-même, vous recevez 402 verification_declined (ou identity_already_registered) avec un message neutre : vérifiez les informations et les photos, puis renvoyez.

verification.status passe à in_review, puis à verified ou rejected, annoncé par cardholder.kyc_updated. Après un refus, lisez verification.reason (par exemple « Name/dob mismatch »), corrigez la cause et renvoyez la vérification. Causes fréquentes : photo floue, pièce expirée, pièce illisible, visage non concordant, pièce recadrée. Vous pouvez envoyer 5 vérifications par titulaire et par 24 heures.

La vérification est propre à chaque entreprise : une personne déjà vérifiée par une autre entreprise est vérifiée à nouveau pour la vôtre. Au sein de votre entreprise, une identité vérifiée peut être réutilisée. En mode test, décidez vous-même avec l’outil de test.

3. Émettre la carte#

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

amount (en cents) est prélevé sur le solde cartes. Il paie les frais d’émission et le reste devient le solde de la carte ; au moins 1 $ doit rester. La carte revient en général active (201). Si l’émetteur prend plus de temps, ou si sa réponse n’est pas encore définitive, vous recevez 202 avec status: "pending", puis card.issued ou card.issue_failed. L’argent ne revient au solde cartes qu’une fois l’échec définitif.

Le numéro complet et le CVC ne passent jamais par l’API. Un membre Propriétaire ou Finance peut les afficher 60 secondes dans le tableau de bord, avec Afficher les données, pour les transmettre au titulaire.

4. Gérer la carte#

Chaque action répond 200 avec la carte, ou 202 quand la réponse de l’émetteur n’est pas encore définitive : l’action n’a pas échoué, et son résultat arrive par webhook (card.funded, card.withdrawn, card.frozen, card.unfrozen, card.terminated).

Les dépenses apparaissent comme transactions card_payment avec l’identifiant de la carte, et comme événements card.transaction. Les tentatives refusées envoient card.authorization_declined.

Cartes à usage unique#

Créez une carte avec "single_use": true pour un achat ponctuel :

• La carte peut être débitée une fois. Les paiements suivants sont refusés et rien n’est prélevé.
• Elle ne peut être ni rechargée ni vidée (400 card_single_use).
• spending_limit ne s’applique pas : le montant de la carte fait office de plafond. Envoyer les deux renvoie 400 parameter_invalid.
• Son solde restant revient au solde cartes à sa résiliation : automatique 30 jours après l’émission, ou plus tôt avec terminate.

Ce que l’émetteur peut faire#

• Résilier une carte après des refus répétés pour fonds insuffisants. Vous recevez card.terminated. Gardez assez d’argent sur les cartes qui paient des abonnements.
• Régler une pré-autorisation pour plus que le montant autorisé. Les hôtels et les loueurs de voitures le font souvent. Gardez une marge sur la carte.
• Prélever plus tard des frais internationaux ou sans contact, si le solde de la carte était trop bas au moment du paiement.

Frais des cartes#

Tous les frais d’une carte sont pris sur la carte elle-même. Vos tarifs en vigueur sont affichés dans le tableau de bord (Paramètres › Tarifs › Cartes, avec le relevé mensuel des frais) et dans l’Annexe 1 de votre contrat.

Pour obtenir les frais d’un paiement, listez les transactions card_fee et gardez celles dont fee.payment est l’identifiant du paiement. Dans le tableau de bord, ils s’affichent sous le paiement, et le relevé mensuel des frais se télécharge en CSV ou en PDF depuis Paramètres › Tarifs › Cartes.

• Solde insuffisant : le frais est inscrit en attente puis prélevé automatiquement à la recharge suivante. Pour la maintenance mensuelle, une nouvelle tentative est faite automatiquement le 15e jour après l’échéance (« Maintenance en attente — nouvelle tentative le … » sur la carte) ; si le solde ne suffit toujours pas, elle reste en attente jusqu’à la recharge suivante. La carte n’est jamais résiliée pour des frais de maintenance impayés.
• Fin du mois : ce qui reste dû est prélevé sur le solde cartes. S’il ne suffit pas, l’émission et la recharge des cartes sont suspendues jusqu’au prochain dépôt sur le solde cartes, qui règle la dette.
• Refus répétés : après 3 paiements refusés en 24 heures, la carte est bloquée automatiquement (card.frozen). Débloquez-la quand vous voulez avec POST /v1/cards/{id}/unfreeze.
• Frais réseau différés : certains frais arrivent après le paiement, sur la facture mensuelle de l’émetteur. Monerails les rapproche carte par carte ; un frais déjà prélevé ne l’est jamais deux fois.

Cartes pour agents IA#

Une carte agent appartient à un agent IA plutôt qu’à une personne : elle n’a ni titulaire ni vérification d’identité. Avant la première, un Propriétaire émet une carte agent depuis le tableau de bord (Cartes › Émettre une carte, Pour : Agent IA) ; cela transmet les informations de votre entreprise à l’émetteur (numéro RCCM, adresse, ville, téléphone international). D’ici là, l’API renvoie 400 agent_cards_not_enabled. Ensuite :

{ "type": "agent", "agent_name": "Procurement bot", "amount": 5000, "spending_limit": { "amount": 5000, "interval": "per_transaction" } }

Donnez à chaque agent sa propre carte avec un plafond serré, utilisez une carte à usage unique (sans spending_limit) pour les achats ponctuels, et bloquez la carte quand l’agent est inactif.