Cartes

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

Monerail émet des cartes virtuelles en dollars, par l’intermédiaire d’un émetteur agréé. 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, Cartes › Recharger : en production, en USDT sur TRON (TRC20), une fois le partenaire cartes connecté en production ; en mode test, avec Simuler le dépôt. 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.

1. Créer le titulaire#

curl https://api.monerail.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",
    "id_document": "national_id"
  }'

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

2. Vérifier son identité#

L’émetteur doit vérifier chaque titulaire. Envoyez la vérification avec les informations et les photos de la pièce (JPEG ou PNG, en base64, 4 Mo au plus chacune) :

{
  "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 est requis ; address.postal_code est facultatif.

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.monerail.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.

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.