API de cartes virtuelles : automatiser l'émission de cartes par le code

À quoi sert une API d'émission de cartes

Émettre quelques cartes à la main, ça va. Émettre une carte pour chaque nouveau client, campagne ou fournisseur, et maintenir chacune approvisionnée, devient vite répétitif. Une API d'émission de cartes transforme ces étapes en code :

• Créez automatiquement une carte par entité, par exemple quand un nouveau client s'inscrit dans votre CRM.
• Rechargez les cartes selon un calendrier ou quand leur solde baisse.
• Gelez des cartes instantanément quand un budget est atteint ou qu'un contrat prend fin.
• Synchronisez les transactions avec vos outils de comptabilité ou de reporting.
• Réagissez aux événements en temps réel grâce aux webhooks au lieu d'interroger l'API en boucle.

L'API fait ce que fait le tableau de bord, depuis votre serveur. Chaque carte émise et chaque chargement sont payés depuis le solde de votre compte, que vous approvisionnez par des dépôts en crypto et qui est toujours détenu en USDT.

Obtenir l'accès à l'API de cartes virtuelles

L'accès se fait en trois étapes :

1. Créez une clé. Ouvrez l'accès API dans votre tableau de bord et générez une clé. Les clés commencent par sk_live_.
2. Faites-la activer. Confirmez votre e-mail et effectuez un premier dépôt, puis demandez au support (via un ticket dans le tableau de bord) d'activer l'API pour votre compte.
3. Faites un appel. Consultez votre solde, puis émettez votre première carte.

Tant que votre compte n'est pas prêt, une clé valide reçoit une réponse 403. Vous verrez le code d'erreur onboarding_incomplete tant que votre e-mail n'est pas confirmé et que vous n'avez pas effectué de premier dépôt, puis api_not_enabled tant que l'accès API n'est pas activé.

Il n'existe ni environnement sandbox séparé ni SDK officiel. Vous appelez directement l'API REST avec n'importe quel client HTTP : l'intégration reste simple, mais chaque appel est réel. Testez avec de petits montants.

Les bases : URL de base, authentification et format

• URL de base : https://usdtcryptocard.com/api/v1
• Authentification : envoyez votre clé comme jeton Bearer dans l'en-tête Authorization de chaque requête.
• Format : JSON via HTTPS. Les montants sont en dollars américains avec deux décimales. Les horodatages sont au format ISO 8601 en UTC.
• Pagination : les endpoints de liste acceptent page et per_page.

Gardez la clé sur votre serveur. Quiconque la détient peut déplacer de l'argent sur votre compte : chargez-la depuis une variable d'environnement et ne l'intégrez jamais dans du code navigateur ou mobile.

Votre premier appel

Consulter votre solde est une première requête sans risque :

curl https://usdtcryptocard.com/api/v1/wallet/balance \
  -H "Authorization: Bearer sk_live_..."

La réponse indique votre solde en USDT, les dépôts en attente et ce qui se trouve sur vos cartes :

{
  "balance": 1312.5,
  "currency": "USDT",
  "pending_deposits": 500.0,
  "cards_active": 8,
  "cards_total_balance": 2450.0
}

Les endpoints

L'API compte 15 endpoints répartis sur six ressources.

Tous les paramètres et des exemples de réponses figurent dans la référence de l'API.

Émettre une carte par le code

La création d'une carte choisit un BIN et charge la carte depuis votre solde dans la même requête. Les champs sont :

• bin_id (obligatoire) : le BIN sur lequel émettre. Listez les options avec GET /bins.
• amount (obligatoire) : le chargement initial en USD, prélevé sur votre solde. Le minimum est de 50 $, et les 1 $ de frais d'émission s'y ajoutent.
• label : le nom que vous donnez à la carte.
• spending_limit : un plafond de dépenses en USD.
• allowed_categories : les catégories de commerçants où la carte peut être utilisée, comme la publicité ou les logiciels. Tout le reste est refusé.
• auto_freeze_at : gèle automatiquement la carte quand son solde passe sous ce montant.
• metadata : des paires clé-valeur pour votre propre suivi.

Voici la même requête en Node.js :

const res = await fetch('https://usdtcryptocard.com/api/v1/cards', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.USDTCC_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    bin_id: '491653',
    amount: 500,
    label: 'Meta Ads - Campaign 12',
    spending_limit: 2000,
    allowed_categories: ['advertising'],
    metadata: { campaign: 'fall_2026' },
  }),
});
const card = await res.json();

Un appel réussi renvoie 201 avec l'objet carte : son id, son BIN, son réseau, ses quatre derniers chiffres, son statut, son solde, ainsi que votre label et vos métadonnées. Le résumé omet volontairement le numéro complet et le CVV.

Récupérer le numéro de carte en toute sécurité

GET /cards/{card_id}/details renvoie le numéro de carte complet, le CVV et la date d'expiration. Traitez-le comme une donnée sensible : ne journalisez jamais la réponse, ne la stockez jamais en clair, et ne la récupérez que lorsque vous devez réellement transmettre les données à une personne ou à une page de paiement. Cet endpoint a une limite de débit plus stricte que les autres.

Approvisionner, geler et clôturer

• Recharger : POST /cards/{card_id}/fund avec un amount transfère de l'argent de votre solde vers la carte. Il est utilisable immédiatement.
• Récupérer les fonds : POST /cards/{card_id}/withdraw renvoie le solde de la carte vers votre portefeuille.
• Mettre en pause : POST /cards/{card_id}/freeze suspend toutes les transactions tout en conservant le solde. unfreeze réactive la carte.
• Clôturer : DELETE /cards/{card_id} résilie définitivement la carte et renvoie son solde restant vers votre portefeuille. C'est irréversible.

Les frais habituels s'appliquent à l'activité via l'API, exactement comme dans le tableau de bord : 1 $ par carte émise, 0,30 $ par transaction acceptée (refus gratuits), et recharges de cartes gratuites depuis votre solde. Les dépôts inférieurs à 300 $ sont soumis à 2 % de frais ; à partir de 300 $, aucun. Voir la section tarifs.

Webhooks

Au lieu d'interroger l'API en boucle, enregistrez un endpoint HTTPS avec POST /webhooks, en listant les événements souhaités (ou ["*"] pour tous). Événements disponibles :

• card.created, card.frozen, card.unfrozen, card.terminated, card.funded
• transaction.authorized, transaction.settled, transaction.declined, transaction.refunded
• 3ds.challenge
• deposit.pending, deposit.confirmed

Chaque envoi est signé en HMAC-SHA256 avec le secret de votre endpoint, généré pour vous si vous n'en fournissez pas. Recalculez la signature sur le corps brut de la requête et comparez-la en temps constant avant de faire confiance au contenu :

import crypto from 'node:crypto';

export function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Ne parsez le JSON qu'une fois la vérification réussie, et rendez votre gestionnaire idempotent au cas où un événement arriverait plusieurs fois.

Erreurs et limites de débit

Toute réponse autre que 2xx est accompagnée d'un corps JSON contenant un code error stable sur lequel vous pouvez vous appuyer et un message lisible. Les codes de statut que vous rencontrerez sont 400 (paramètres invalides), 401 (clé absente ou invalide), 403 (compte pas prêt ou API non activée), 404 (introuvable) et 429 (limite de débit dépassée).

Les limites sont comptées par clé API :

Si vous recevez un 429, patientez et réessayez avec un backoff exponentiel.

Conseils de conception pour une intégration fiable

• Stockez l'id de la carte, pas son numéro. Récupérez les détails à la demande.
• Utilisez metadata et label pour relier les cartes à vos propres données, comme un identifiant client ou une campagne.
• Préférez les webhooks à l'interrogation en boucle pour les transactions et les demandes 3D Secure.
• Gardez une marge sur les cartes qui règlent des prélèvements récurrents, ou utilisez auto_freeze_at et fund pour gérer automatiquement les soldes.
• Anticipez les plafonds. Les plafonds de l'offre du compte s'appliquent toujours : l'offre Virtual autorise 5 000 $ par transaction et 20 000 $ par mois, tandis que Platinum, débloquée par un dépôt unique de 300 $ ou plus, n'a pas de plafond de dépenses.

Si vous gérez des cartes pour une équipe plutôt que d'écrire du code, voir cartes virtuelles pour les équipes. Pour les comptes publicitaires, lisez cartes virtuelles pour la publicité. Prêt à commencer ? Créez un compte.

Questions fréquentes

Qu'est-ce qu'une API de cartes virtuelles ?

C'est une interface qui permet à un logiciel de créer et de gérer automatiquement des cartes de paiement. Chez USDT Crypto Card, il s'agit d'une API REST en JSON via HTTPS, authentifiée par une clé secrète sk_live_.

Existe-t-il une sandbox ou un SDK ?

Non. Il n'y a ni environnement sandbox ni SDK officiel. Vous appelez directement l'API REST avec n'importe quel client HTTP, et chaque appel est réel : testez avec de petits montants.

Pourquoi ma nouvelle clé API renvoie-t-elle une erreur 403 ?

Le compte n'est pas encore prêt. onboarding_incomplete signifie que vous devez encore confirmer votre e-mail et effectuer un premier dépôt. api_not_enabled signifie que le support doit encore activer l'accès API.

Comment les webhooks sont-ils sécurisés ?

Chaque envoi est signé en HMAC-SHA256 avec le secret de votre endpoint. Recalculez la signature sur le corps brut et comparez-la en temps constant avant de faire confiance au contenu.

Les cartes émises via l'API coûtent-elles autant que celles du tableau de bord ?

Oui. Les mêmes frais s'appliquent : 1 $ par carte, 0,30 $ par transaction acceptée, recharges gratuites depuis votre solde, et 2 % de frais de dépôt sous 300 $.