Tovanix
Tovanix

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…