Cartes virtuelles

Une carte virtuelle est une carte Visa ou Mastercard en dollars américains, utilisable pour payer en ligne : publicité, abonnements, logiciels, fournisseurs. Elle est alimentée depuis votre solde en USD.

Émettre une carte

1. Ayez des dollars sur votre solde d'encaissement réel. Si vos encaissements sont en XAF ou en XOF, convertissez-les en USD.
2. Enregistrez le titulaire : nom, e-mail, téléphone, adresse et pièce d'identité. L'émetteur de la carte exige l'identité de la personne qui l'utilisera. Un titulaire peut avoir plusieurs cartes.
3. Choisissez le réseau (Visa ou Mastercard), donnez un nom à la carte et indiquez le montant à charger.

Frais

Deux frais s'appliquent, tous deux affichés avant que vous ne confirmiez et prélevés sur votre solde en USD, en plus du montant chargé :

• des frais fixes à l'émission de chaque carte ;
• un pourcentage du montant à chaque chargement, y compris le premier.

Un montant minimum s'applique à chaque chargement. Récupérer de l'argent d'une carte vers votre solde est gratuit.

Gérer une carte

La page d'une carte affiche son solde en temps réel, les paiements effectués avec elle et l'historique de ses chargements.

Sécurité

• Loov ne conserve ni le numéro complet de la carte, ni sa date d'expiration, ni son code de sécurité. Seuls les derniers chiffres sont enregistrés.
• Pour les afficher, vous devez saisir votre mot de passe. Ils sont alors lus chez l'émetteur, montrés une seule fois, et chaque consultation est inscrite dans le journal d'activité de votre compte.
• Quiconque détient ces informations peut dépenser le solde de la carte. En cas de doute, bloquez la carte immédiatement.

Statuts

Intégrer les cartes par l'API

Tout ce que fait le tableau de bord est disponible par l'API, pour émettre et gérer des cartes depuis votre propre application. Les cartes sont réelles : ces routes exigent une clé réelle (loov_live_…) et répondent live_key_required avec une clé de test. Les montants sont en cents de dollar.

1. Enregistrer un titulaire

curl -X POST https://api.secure.payment.loov-solutions.com/v2/cardholders \
  -H "Authorization: Bearer $LOOV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Awa",
  "last_name": "Ndiaye",
  "email": "awa@example.com",
  "phone": "+237650000000",
  "country": "CM",
  "state": "Littoral",
  "city": "Douala",
  "address": "12 rue de la Joie",
  "zip_code": "00237",
  "id_type": "National_ID",
  "id_number": "123456789"
}'

id_type vaut National_ID, Passport ou Driving_License. Le téléphone est au format international avec le signe +. Conservez l' id renvoyé : il sert à émettre les cartes.

2. Émettre une carte

curl -X POST https://api.secure.payment.loov-solutions.com/v2/cards \
  -H "Authorization: Bearer $LOOV_API_KEY" \
  -H "Idempotency-Key: 6f1c2b9e-order-42" \
  -H "Content-Type: application/json" \
  -d '{
  "cardholder": "01k6x3v9q2m8h4n7b5t0c1d2e3",
  "title": "Publicité en ligne",
  "brand": "visa",
  "amount": 5000
}'

{
  "card": {
    "id": "01k6x4a7r9w2e5t8y1u3i6o0p4",
    "cardholder": "01k6x3v9q2m8h4n7b5t0c1d2e3",
    "title": "Publicité en ligne",
    "brand": "visa",
    "mask": "451946******1642",
    "currency": "USD",
    "status": "active",
    "created_at": "2026-10-05T10:12:00+00:00"
  },
  "operation": {
    "id": "01k6x4a7q1z3x5c7v9b2n4m6k8",
    "card": "01k6x4a7r9w2e5t8y1u3i6o0p4",
    "type": "issue",
    "currency": "USD",
    "amount": 5000,
    "fee": 375,
    "status": "succeeded",
    "created_at": "2026-10-05T10:12:00+00:00"
  }
}

amount est le montant chargé sur la carte ; fee est prélevé en plus sur votre solde en USD.

3. Charger, retirer, suivre

curl -X POST https://api.secure.payment.loov-solutions.com/v2/cards/{id}/fund \
  -H "Authorization: Bearer $LOOV_API_KEY" \
  -H "Idempotency-Key: 6f1c2b9e-order-42" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 2000
}'

Le chargement et le retrait renvoient l'opération. GET /v2/cards/{id} renvoie la carte avec balance, son solde chez l'émetteur à l'instant de l'appel.

Quand l'émetteur ne répond pas

Si l'émetteur ne répond pas à une émission, un chargement ou un retrait, l'API répond 202 avec l'opération au statut unknown (et card: null pour une émission). Le montant reste réservé le temps que notre équipe vérifie. Ne relancez pas avec une nouvelle clé d'idempotence : interrogez GET /v2/card-operations/{id} jusqu'à succeeded ou failed.

Afficher les informations de la carte

curl -X GET https://api.secure.payment.loov-solutions.com/v2/cards/{id}/details \
  -H "Authorization: Bearer $LOOV_API_KEY" \
  -H "Accept: application/json"

{
  "id": "01k6x4a7r9w2e5t8y1u3i6o0p4",
  "number": "4519460000001642",
  "security_code": "809",
  "expiry": "1030",
  "name": "Awa Ndiaye",
  "billing_address": null
}

• Appelez cette route depuis votre serveur, uniquement au moment où le titulaire demande à voir sa carte, après l'avoir authentifié.
• N'enregistrez jamais la réponse, ni en base de données, ni dans vos journaux, ni en cache.
• Chaque appel est inscrit dans le journal d'activité de votre compte.

Activité de la carte et notifications

Chaque événement signalé par l'émetteur sur une carte est enregistré, met à jour le solde de la carte (balance, dans la plus petite unité) et son statut, et vous est notifié à l'adresse webhook que vous définissez pour vos cartes dans le tableau de bord (page « Cartes virtuelles », « Notifications des cartes »). Cette adresse est distincte de celles de vos applications et possède son propre secret de signature. Un paiement refusé, des frais de carte impayés et une carte clôturée ou remplacée vous sont aussi signalés par e-mail.

curl -X GET https://api.secure.payment.loov-solutions.com/v2/cards/{id}/activity?kind=decline \
  -H "Authorization: Bearer $LOOV_API_KEY" \
  -H "Accept: application/json"

{
  "event": "card.payment_declined",
  "data": {
    "card": {
      "id": "01k6x4a7r9w2e5t8y1u3i6o0p4",
      "title": "Publicité en ligne",
      "brand": "visa",
      "mask": "451946******1642",
      "status": "active",
      "currency": "USD",
      "balance": 200,
      "balance_updated_at": "2026-10-07T11:20:04+00:00"
    },
    "transaction": {
      "id": "01k7c0d2f4g6h8j0k2m4n6p8q0",
      "kind": "decline",
      "status": "declined",
      "amount": 500,
      "currency": "USD",
      "merchant": "aliexpress",
      "city": "New York",
      "country": "United States",
      "reason": "Insufficient funds",
      "balance_after": 200,
      "occurred_at": "2026-10-07T11:20:03+00:00"
    }
  }
}

Messages d'erreur