API des cartes virtuelles
Émettez et gérez en masse des cartes virtuelles Visa / Mastercard par API, alimentées en USDT, pour abonnements, publicité et achats internationaux.
- Recherche BIN : BIN disponibles, régions prises en charge et plages de limites
- Émission et recharge : créez des cartes avec le BIN choisi et rechargez selon les besoins
- Gestion : gel, dégel, clôture et récupération sécurisée des données de carte
- Transactions et webhooks : historique individuel et événements d'autorisation et de règlement en temps réel
Vue d’ensemble
L’API ouverte des cartes virtuelles permet d’ouvrir des cartes, lister les BIN, lire les détails, obtenir les codes OTP 3DS, consulter les transactions, recharger et résilier. Elle permet aussi de lire votre solde USD et d’obtenir une adresse de dépôt TRON fixe dédiée. Tous les points renvoient la structure JSON code/message/data, code=0 indiquant un succès.
URL de base = adresse de votre passerelle, l’origine de ce site. Préfixe des cartes : /api/v1/vcard ; du compte : /api/v1/account.
Tous les montants sont en USD ; ouverture et recharge sont débitées du solde USD de la plateforme, uniquement par solde. Un solde insuffisant renvoie une erreur.
Authentification et signature
Les points de lecture, BIN, liste de cartes, transactions, commandes, solde et adresse de dépôt, acceptent les deux clés simples. Ceux qui déplacent des fonds ou renvoient des données sensibles exigent aussi signature HMAC, horodatage et nonce anti-rejeu : ouverture, recharge, résiliation, restitution, gel/dégel, détails complets (details) et code 3DS (code). Une clé simple divulguée ne suffit donc pas à déplacer des fonds ou lire les données sensibles.
Connectez-vous à la console → Outils et paramètres → Gestion API → Créer une clé, puis copiez API Key et Secret Key ; le secret n’est affiché qu’une fois.
Ouverture, recharge, résiliation, restitution, gel/dégel, détails complets avec numéro et CVV et code 3DS n’acceptent que des requêtes signées ; les clés seules renvoient 401. Les autres lectures ne nécessitent pas de signature.
Solde du compte
GET /api/v1/account/balance
Lisez le solde USD actuel, avec l’adresse TRON fixe dédiée si possible. deposit_address est null si le pool d’adresses est temporairement indisponible ; le solde reste renvoyé.
Adresse TRON fixe
GET /api/v1/account/deposit-address
Obtenez ou attribuez votre adresse TRON fixe dédiée (USDT/TRX·TRC20). Sans commande : tout montant reçu est converti en USD et crédité automatiquement, idéal pour les recharges par API. L’adresse reste fixe après attribution.
Champs de réponse
Envoyez USDT ou TRX à cette adresse ; après confirmation par le scanner de blocs, le montant est converti en USD au taux actuel et crédité à votre solde, sans callback nécessaire.
État des services
GET /api/v1/vcard/info
Renvoie l’activation du service de cartes virtuelles et le solde USD actuel.
Champs de réponse
Si le solde du compte ne peut pas être lu, le point d’accès renvoie HTTP 503 au lieu de balance: 0. Réessayez plus tard ; ne l’interprétez pas comme un solde nul.
BIN des cartes
GET /api/v1/vcard/bins
Renvoie les BIN de cartes. Les frais sont des prix finaux avec majoration, calculés selon votre palier API de consommation sur 30 jours : plus de dépenses, taux plus bas. can_open=false marque les BIN réservés à la recharge des cartes existantes, sans ouverture nouvelle.
Ouvrir une carte Signé
POST /api/v1/vcard/cards
Créez une carte. Le système débite du solde USD les frais d’ouverture, de recharge et le montant chargé ; la commande est traitée de manière asynchrone via une file.
Champs de réponse
L’ouverture est asynchrone : après réception de order_id et status=queued, interrogez les détails jusqu’à completed. Les échecs sont remboursés automatiquement sur votre solde.
Après un délai dépassé ou une coupure, la facturation peut déjà avoir eu lieu. Ne réessayez pas avec un nouveau numéro : renvoyez le même out_trade_no (commande existante renvoyée telle quelle, sans nouvelle facturation), ou consultez GET /api/v1/vcard/orders/by-trade-no/:out_trade_no. Sans out_trade_no, cette protection n’existe pas et une nouvelle tentative peut être facturée à nouveau.
Liste des cartes
GET /api/v1/vcard/cards
Renvoie toutes les cartes du compte : numéro masqué sur les 4 derniers chiffres, solde, état d’utilisation et de résiliation.
Champs de réponse
La liste des cartes ne renvoie que les champs du tableau ci-dessus. can_return et fee_return sont présents seulement pour certains BIN ; s’ils sont absents, considérez que la restitution du solde n’est pas prise en charge.
Détails de la carte Signé
GET /api/v1/vcard/cards/:id/details
Renvoie les données sensibles en clair d’une carte : numéro complet, CVV, expiration, titulaire. Seules vos cartes sont consultables.
Champs de réponse
Remarque : le tableau liste les champs garantis par la plateforme. La réponse peut en contenir d’autres ; c’est la réponse effective qui fait foi.
Ce point renvoie le numéro complet et le CVV ; appelez-le uniquement depuis un serveur de confiance, sans les exposer dans l’interface ni les journaux.
Transactions
GET /api/v1/vcard/cards/:id/transactions
Renvoie les transactions et relevés de la carte, dépenses, recharges, etc. ; chaque requête synchronise en temps réel les dernières opérations.
Champs de réponse
Remarque : le tableau liste les champs garantis par la plateforme. La réponse peut en contenir d’autres ; c’est la réponse effective qui fait foi.
Code OTP Signé
GET /api/v1/vcard/cards/:id/code
Obtenez le dernier code OTP 3DS de la carte pour vérifier un paiement.
Recharger Signé
POST /api/v1/vcard/cards/:id/recharge
Rechargez une carte existante. Montant et frais sont débités du solde USD ; traitement asynchrone via une file.
Champs de réponse
Après un délai dépassé ou une coupure, la facturation peut déjà avoir eu lieu. Ne réessayez pas avec un nouveau numéro : renvoyez le même out_trade_no (commande existante renvoyée telle quelle, sans nouvelle facturation), ou consultez GET /api/v1/vcard/orders/by-trade-no/:out_trade_no. Sans out_trade_no, cette protection n’existe pas et une nouvelle tentative peut être facturée à nouveau.
Annuler Signé
POST /api/v1/vcard/cards/:id/cancel
Soumettez une résiliation. Elle est asynchrone : après confirmation bancaire, pouvant prendre plusieurs jours, le solde restant est remboursé automatiquement sur votre compte.
Restitution du solde Signé
POST /api/v1/vcard/cards/:id/return
Restituez le solde restant au compte sans résilier la carte. Les frais sont déduits du montant restitué et le net est crédité automatiquement. Certains BIN seulement : can_return doit être true dans la liste ; fee_return est le frais de restitution du BIN.
Une seule restitution à la fois par carte. Une nouvelle demande pendant le traitement renvoie 400 ; attendez un état final au lieu de répéter la même requête.
Geler / Dégeler Signé
POST /api/v1/vcard/cards/:id/freeze
Gelez ou dégelez une carte. Chaque opération facture un petit frais, voir status_fee dans la liste. Seulement si can_freeze=true ; renvoie 400 si l’état cible est déjà atteint ou une opération précédente est en cours.
Recharge automatique (règles de solde) Signé
GET /api/v1/vcard/balance-rules
GET /api/v1/vcard/cards/:id/balance-rule
PUT /api/v1/vcard/cards/:id/balance-rule
DELETE /api/v1/vcard/cards/:id/balance-rule
POST /api/v1/vcard/cards/:id/balance-rule/resume
Recharge une carte automatiquement quand son solde passe sous un montant fixé, ou envoie seulement un rappel. Chaque carte a une règle ; PUT la crée ou la remplace. Les recharges automatiques suivent le même circuit de débit que les recharges manuelles (mêmes plafonds et frais) et se déclenchent quand le solde change ou lors d’une vérification chaque minute.
Limites de sécurité : un nombre quotidien de recharges (1–10, dans le fuseau de votre compte) et un plafond mensuel sont obligatoires. La règle se met en pause et vous prévient si la carte est gelée ou en cours de clôture, si l’émetteur refuse pour fraude, si 3 transactions d’affilée sont refusées ou si le solde du compte manque 3 fois de suite. Appelez resume pour la relancer (les règles mises en pause par la plateforme ne peuvent pas être relancées par vous).
Les clés d’API avec un plafond de dépenses quotidien ne peuvent pas créer ni relancer la recharge automatique (403, code 4035) : la plateforme débite les recharges automatiques en arrière-plan, hors du plafond de la clé. Les règles de simple rappel ne sont pas concernées.
Abonnements
GET /api/v1/vcard/subscriptions
Prélèvements récurrents repérés dans les transactions de vos cartes actives (lecture seule, calculé à la volée) : des prélèvements répétés du même commerçant à environ une semaine, un mois ou un an d’intervalle comptent comme un abonnement. Pour en arrêter un, gelez ou clôturez la carte.
Commerçants autorisés Signé
GET /api/v1/vcard/merchant-locks
GET /api/v1/vcard/cards/:id/merchant-lock
PUT /api/v1/vcard/cards/:id/merchant-lock
DELETE /api/v1/vcard/cards/:id/merchant-lock
Définit les commerçants avec lesquels une carte peut être utilisée. Si une transaction d’un autre commerçant apparaît, la carte est gelée automatiquement (des frais de gel) ou vous êtes seulement prévenu. Seules les transactions après l’enregistrement sont vérifiées, et le gel intervient après coup : la première transaction hors liste est déjà autorisée.
Groupes de cartes
GET /api/v1/vcard/groups
POST /api/v1/vcard/groups
PUT /api/v1/vcard/groups/:gid
DELETE /api/v1/vcard/groups/:gid
POST /api/v1/vcard/cards/group
Rangez vos cartes en groupes, chacun avec un budget mensuel facultatif : une alerte à 80 % et une autre en cas de dépassement ; les transactions ne sont jamais bloquées. Une carte appartient à un seul groupe ; group_id 0 la retire de son groupe. Jusqu’à 20 groupes.
Relevé mensuel
GET /api/v1/vcard/bill/export
Les transactions de carte d’un mois, éventuellement pour une seule carte ou un groupe, de la plus ancienne à la plus récente. Seules les transactions de la période où vous déteniez la carte sont incluses ; au-delà de 20 000 lignes vous recevez 400 : exportez par carte ou par groupe.
Liste des commandes
GET /api/v1/vcard/orders
Liste paginée de vos commandes d’ouverture, recharge et résiliation.
Détails de commande
GET /api/v1/vcard/orders/:id
Consultez l’avancement d’une commande pour suivre le résultat après ouverture ou recharge.
Renvoie un objet commande avec exactement les mêmes champs que dans « Consulter les commandes ».
Rechercher avec votre propre numéro de commande
GET /api/v1/vcard/orders/by-trade-no/:out_trade_no
Recherche par out_trade_no fourni à l’ouverture ou au rechargement d’une carte. La réponse est identique aux détails de commande. Renvoie 404 si le numéro n’existe pas.
Mettre à jour la remarque
PUT /api/v1/vcard/cards/:id/remark
Définissez une remarque sur une carte, maximum 60 caractères.
Notification webhook
Lors d’événements, ouverture, recharge, résiliation, transaction ou code 3DS, la plateforme notifie votre point par HTTP POST JSON, sans interrogation. Configurez dans Console → Carte virtuelle → Intégration API : activation, URL, secret et événements. Aucun événement coché signifie tous.
Livraison : URL https publique, objet JSON plat dont toutes les valeurs sont des chaînes. Une réponse 2xx marque le succès ; sinon réessais exponentiels 30s → 1m → 2m → 5m → 10m, jusqu’à 10 tentatives. Même notify_id pour les réessais : dédupliquez avec cet ID.
Champs communs à chaque événement ; champs spécifiques ci-dessous :
Vérification : prenez tous les champs non vides sauf "sign", triez les clés en ordre croissant, joignez en k=v&k2=v2, calculez HMAC-SHA256 hexadécimal minuscule avec votre secret et comparez à sign. Exigez aussi sign_ts à ±5 minutes et un nonce inédit. Rejetez avec 401 si une vérification échoue.
Événements et champs spécifiques :
Questions fréquentes
Quand la carte est-elle utilisable et où peut-on payer ?
L'émission renvoie les données de carte en quelques secondes. Elle fonctionne immédiatement partout où les paiements en ligne Visa / Mastercard sont acceptés, notamment abonnements IA, plateformes publicitaires et commerce international.
Comment diagnostiquer une transaction refusée ?
Consultez l'historique des transactions pour le code de refus de cette autorisation : généralement solde insuffisant, catégorie de commerçant restreinte ou blocage de risque. Les événements d'autorisation et de règlement sont aussi transmis par webhooks pour rapprochement.
Pages connexes: Cartes virtuelles · Documentation API · Paiements crypto multichaînes
Chargement…