Tovanix
Tovanix

API für virtuelle Karten

Virtuelle Visa-/Mastercard-Karten per API in großer Zahl ausgeben und verwalten, mit USDT bezahlen. Für Abonnementabrechnung, Werbeausgaben und internationalen Einkauf.

  • BIN-Abfrage: verfügbare BINs, unterstützte Regionen und Limitbereiche
  • Ausgabe und Aufladung: Karten mit gewähltem BIN erstellen und nach Bedarf aufladen
  • Kartenverwaltung: sperren, entsperren, schließen und Kartendaten sicher abrufen
  • Umsätze und Webhooks: Verlauf je Transaktion sowie Autorisierungs- und Abrechnungsereignisse in Echtzeit

Übersicht

Mit der offenen API für virtuelle Karten können Sie Karten eröffnen, BINs auflisten, Kartendetails und 3DS-OTP-Codes abrufen, Transaktionen abfragen, aufladen und kündigen. Außerdem können Sie Ihr USD-Kontoguthaben lesen und eine eigene feste TRON-Einzahlungsadresse abrufen. Alle Endpunkte liefern dieselbe JSON-Struktur: code/message/data, code=0 bedeutet Erfolg.

Basis-URL = Ihre Gateway-Adresse, also der Ursprung dieser Website. Kartenendpunkte beginnen mit /api/v1/vcard, Kontoendpunkte mit /api/v1/account.

Alle Beträge in USD. Eröffnung und Aufladung werden vom USD-Plattformguthaben abgebucht, nur Guthabenzahlung. Unzureichendes Guthaben liefert einen Fehler.

Authentifizierung und Signierung

Leseendpunkte für BINs, Kartenliste, Transaktionen, Aufträge, Guthaben und Einzahlungsadresse akzeptieren die beiden einfachen Schlüssel. Endpunkte mit Geldbewegungen oder vertraulichen Daten erfordern zusätzlich HMAC-Signierung, Zeitstempel und nonce zum Wiederholungsschutz: Eröffnung, Aufladung, Kündigung, Guthabenrückführung, Sperren/Entsperren sowie vollständige Kartendetails (details) und 3DS-Code (code). Ein offengelegter einfacher Schlüssel allein kann somit weder Geld bewegen noch vertrauliche Kartendaten lesen.

Konsole öffnen → Werkzeuge und Einstellungen → API-Verwaltung → Schlüssel erstellen. API Key und Secret Key kopieren; der Geheimschlüssel wird nur einmal angezeigt.

Eröffnung, Aufladung, Kündigung, Guthabenrückführung, Sperren/Entsperren, vollständige Kartendetails mit Nummer und CVV sowie 3DS-Code akzeptieren nur signierte Anfragen; einfache Schlüssel allein liefern 401. Andere Leseendpunkte benötigen keine Signierung.

Kontoguthaben

GET /api/v1/account/balance

Aktuelles USD-Kontoguthaben lesen, wenn möglich mit eigener fester TRON-Einzahlungsadresse. deposit_address ist null bei vorübergehend nicht verfügbarem Adresspool; das Guthaben wird trotzdem zurückgegeben.

Feste TRON-Adresse

GET /api/v1/account/deposit-address

Eigene feste TRON-Einzahlungsadresse abrufen/zuweisen (USDT/TRX·TRC20). Kein Auftrag erforderlich: Jeder überwiesene Betrag wird automatisch in USD umgerechnet und gutgeschrieben. Ideal für automatische API-Aufladungen. Nach Zuweisung bleibt die Adresse fest.

Antwortfelder

Senden Sie USDT oder TRX an diese Adresse. Nach Bestätigung durch den Blockscanner erfolgt die automatische Umrechnung zum aktuellen Kurs in USD und Gutschrift auf Ihr Plattformguthaben; kein Callback nötig.

Dienststatus

GET /api/v1/vcard/info

Gibt zurück, ob virtuelle Karten aktiviert sind, sowie das aktuelle USD-Kontoguthaben.

Antwortfelder

Kann das Kontoguthaben nicht gelesen werden, liefert der Endpunkt HTTP 503 statt balance: 0. Bei 503 später erneut versuchen; nicht als Nullguthaben behandeln.

Karten-BINs

GET /api/v1/vcard/bins

Gibt die Karten-BIN-Liste zurück. Gebühren sind Endpreise mit Plattformaufschlag, nach der API-Stufe Ihres Verbrauchs der letzten 30 Tage: mehr Verbrauch bedeutet niedrigeren Satz. can_open=false kennzeichnet BINs nur zur Aufladung bestehender Karten, keine Neueröffnung.

Karte eröffnen Signiert

POST /api/v1/vcard/cards

Neue Karte erstellen. Das System bucht Eröffnungsgebühr, Aufladegebühr und Kartenguthaben vom USD-Kontoguthaben ab. Der Auftrag wird asynchron über eine Warteschlange verarbeitet.

Antwortfelder

Eröffnung ist asynchron. Nach Antwort mit order_id und status=queued die Auftragsdetails bis completed abfragen. Bei Fehlern wird automatisch auf das Kontoguthaben erstattet.

Bei Zeitüberschreitung oder Verbindungsabbruch kann die Belastung bereits erfolgt sein. Nicht mit einer neuen Auftragsnummer wiederholen: Dieselbe out_trade_no erneut senden (bestehender Auftrag unverändert, keine erneute Belastung) oder über GET /api/v1/vcard/orders/by-trade-no/:out_trade_no nachsehen. Anfragen ohne out_trade_no haben diesen Schutz nicht; eine Wiederholung kann doppelt belasten.

Kartenliste

GET /api/v1/vcard/cards

Gibt alle Karten Ihres Kontos zurück: maskierte Nummer mit letzten 4 Ziffern, Guthaben, Nutzungs- und Kündigungsstatus.

Antwortfelder

Die Kartenliste enthält nur die oben aufgeführten Felder. can_return und fee_return werden nur bei einigen BINs geliefert; fehlen sie, gilt Guthabenrückgabe als nicht unterstützt.

Kartendetails Signiert

GET /api/v1/vcard/cards/:id/details

Gibt vertrauliche Klartextdaten einer Karte zurück: vollständige Nummer, CVV, Ablaufdatum und Inhaber. Nur eigene Karten abfragbar.

Antwortfelder

Hinweis: Die Tabelle nennt die von der Plattform garantierten Felder. Die Antwort kann weitere Felder enthalten; maßgeblich ist die tatsächliche Rückgabe.

Dieser Endpunkt liefert vollständige Kartennummer und CVV. Nur von vertrauenswürdigem Server aufrufen; niemals in Frontends oder Protokollen offenlegen.

Transaktionen

GET /api/v1/vcard/cards/:id/transactions

Gibt Kartenumsätze und Abrechnungsdaten wie Ausgaben und Aufladungen zurück; bei jeder Abfrage werden die neuesten Umsätze in Echtzeit synchronisiert.

Antwortfelder

Hinweis: Die Tabelle nennt die von der Plattform garantierten Felder. Die Antwort kann weitere Felder enthalten; maßgeblich ist die tatsächliche Rückgabe.

OTP-Code Signiert

GET /api/v1/vcard/cards/:id/code

Neuesten 3DS-OTP-Code der Karte zur Zahlungsbestätigung abrufen.

Aufladen Signiert

POST /api/v1/vcard/cards/:id/recharge

Bestehende Karte aufladen. Aufladebetrag und Gebühr werden vom USD-Kontoguthaben abgebucht; asynchrone Verarbeitung über Warteschlange.

Antwortfelder

Bei Zeitüberschreitung oder Verbindungsabbruch kann die Belastung bereits erfolgt sein. Nicht mit einer neuen Auftragsnummer wiederholen: Dieselbe out_trade_no erneut senden (bestehender Auftrag unverändert, keine erneute Belastung) oder über GET /api/v1/vcard/orders/by-trade-no/:out_trade_no nachsehen. Anfragen ohne out_trade_no haben diesen Schutz nicht; eine Wiederholung kann doppelt belasten.

Abbrechen Signiert

POST /api/v1/vcard/cards/:id/cancel

Kartenkündigung einreichen. Kündigung ist asynchron: Nach Bankbestätigung, die Tage dauern kann, wird das Restguthaben automatisch auf Ihr Kontoguthaben erstattet.

Guthabenrückführung Signiert

POST /api/v1/vcard/cards/:id/return

Restguthaben auf Ihr Kontoguthaben zurückführen, ohne die Karte zu kündigen. Gebühr wird vom Rückführungsbetrag abgezogen, der Nettobetrag automatisch gutgeschrieben. Nur bei einigen BINs: aufrufbar, wenn can_return in der Kartenliste true ist; fee_return ist deren Rückführungsgebühr.

Je Karte ist nur eine Rückführung gleichzeitig zulässig. Solange eine läuft, liefert erneutes Einreichen 400. Warten Sie auf einen Endstatus statt dieselbe Anfrage zu wiederholen.

Sperren / Entsperren Signiert

POST /api/v1/vcard/cards/:id/freeze

Karte sperren oder entsperren. Je Aktion fällt eine kleine Gebühr an, siehe status_fee in der Kartenliste. Nur bei can_freeze=true aufrufbar; 400, wenn Zielstatus bereits erreicht oder eine vorherige Aktion noch läuft.

Automatische Aufladung (Guthabenregeln) Signiert

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

Lädt eine Karte automatisch auf, wenn ihr Guthaben unter einen festgelegten Betrag fällt, oder sendet nur eine Erinnerung. Pro Karte gibt es eine Regel; PUT legt sie an oder ersetzt sie. Automatische Aufladungen laufen über denselben Abbuchungsweg wie manuelle (gleiche Limits und Gebühren) und werden bei Guthabenänderungen oder einer minütlichen Prüfung ausgelöst.

Sicherheitsgrenzen: Eine tägliche Anzahl von Aufladungen (1–10, in der Zeitzone Ihres Kontos) und ein monatliches Betragslimit sind Pflicht. Die Regel pausiert automatisch und benachrichtigt Sie, wenn die Karte gesperrt ist oder gekündigt wird, der Aussteller wegen Betrug ablehnt, 3 Transaktionen in Folge abgelehnt werden oder Ihr Kontoguthaben 3-mal in Folge nicht reicht. Mit resume setzen Sie sie fort (von der Plattform pausierte Regeln können Sie nicht selbst fortsetzen).

API-Schlüssel mit täglichem Ausgabenlimit können keine automatische Aufladung anlegen oder fortsetzen (403, Geschäftscode 4035): Die Plattform bucht automatische Aufladungen im Hintergrund ab, außerhalb des Schlüssellimits. Reine Erinnerungsregeln sind nicht betroffen.

Abonnements

GET /api/v1/vcard/subscriptions

Wiederkehrende Abbuchungen, erkannt aus den Transaktionen Ihrer aktiven Karten (nur lesend, live berechnet): Wiederholte Abbuchungen desselben Händlers im Abstand von etwa einer Woche, einem Monat oder einem Jahr gelten als Abonnement. Zum Beenden die Karte sperren oder kündigen.

Händlersperre Signiert

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

Legt fest, bei welchen Händlern eine Karte verwendet werden darf. Taucht eine Transaktion eines anderen Händlers auf, wird die Karte automatisch gesperrt (eine Sperrgebühr) oder Sie werden nur benachrichtigt. Geprüft werden nur Transaktionen nach dem Speichern, und die Sperre erfolgt nachträglich — die erste Transaktion außerhalb der Liste ist bereits autorisiert.

Kartengruppen

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

Ordnen Sie Karten in Gruppen, jeweils mit optionalem Monatsbudget: Sie erhalten eine Meldung bei 80 % und eine bei Überschreitung; Transaktionen werden nie blockiert. Eine Karte gehört höchstens einer Gruppe an; group_id 0 entfernt sie aus der Gruppe. Bis zu 20 Gruppen.

Monatsabrechnung

GET /api/v1/vcard/bill/export

Die Kartentransaktionen eines Monats, optional für eine Karte oder eine Gruppe, älteste zuerst. Enthalten sind nur Transaktionen aus der Zeit, in der Sie die Karte besaßen; würden mehr als 20.000 Zeilen zurückkommen, gibt es 400 — exportieren Sie dann nach Karte oder Gruppe.

Auftragsliste

GET /api/v1/vcard/orders

Seitenweise Liste Ihrer Eröffnungs-, Auflade- und Kündigungsaufträge.

Auftragsdetails

GET /api/v1/vcard/orders/:id

Fortschritt eines Auftrags abfragen, zum Prüfen der Ergebnisse nach Eröffnung/Aufladung.

Gibt ein Auftragsobjekt mit genau denselben Feldern wie in „Aufträge abfragen“ zurück.

Auftrag anhand Ihrer eigenen Auftragsnummer suchen

GET /api/v1/vcard/orders/by-trade-no/:out_trade_no

Sucht anhand der beim Eröffnen oder Aufladen einer Karte übergebenen out_trade_no. Die Antwort entspricht den Auftragsdetails. 404, wenn die Nummer nicht existiert.

Anmerkung aktualisieren

PUT /api/v1/vcard/cards/:id/remark

Eigene Kartenanmerkung festlegen (höchstens 60 Zeichen).

Webhook-Push

Bei Kartenereignissen (Eröffnung, Aufladung, Kündigung, neue Transaktion oder neuer 3DS-Code) sendet die Plattform HTTP-POST-JSON an Ihren Endpunkt, ohne Abfragen. Konfiguration unter Konsole → Virtuelle Karte → API-Integration: Schalter, Endpunkt-URL, Signierungsgeheimnis und Ereignisauswahl; keine ausgewählten Ereignisse bedeutet alle abonnieren.

Zustellregeln: öffentlich erreichbare https-URL; flaches JSON-Objekt mit ausschließlich Zeichenfolgenwerten. 2xx bestätigt Erfolg. Sonst exponentielle Wiederholung: 30s → 1m → 2m → 5m → 10m, höchstens 10 Versuche. Wiederholungen tragen dieselbe notify_id; damit idempotent deduplizieren.

Gemeinsame Felder aller Ereignisse; spezifische Felder unten:

Prüfung: Alle nicht leeren Felder außer "sign" nach Schlüssel aufsteigend sortieren, als k=v&k2=v2 verketten und HMAC-SHA256 mit Ihrem Geheimschlüssel berechnen, hexadezimal in Kleinbuchstaben. Mit sign vergleichen. Außerdem sign_ts innerhalb ±5 Minuten und bisher unbekanntes nonce verlangen. Bei Fehler einer Prüfung mit 401 ablehnen.

Ereignisse und spezifische Felder:

Häufig gestellte Fragen

Wie schnell kann eine Karte genutzt werden, und wo?

Bei Ausgabe werden die Kartendaten innerhalb von Sekunden zurückgegeben. Die Karte funktioniert sofort überall, wo Visa-/Mastercard-Onlinezahlungen angenommen werden, häufig für KI-Abonnements, Werbeplattformen und internationalen Onlinehandel.

Wie untersuche ich eine abgelehnte Transaktion?

Fragen Sie den Transaktionsverlauf nach dem Ablehnungsgrund dieser Autorisierung ab. Häufig sind zu wenig Guthaben, eine gesperrte Händlerkategorie oder eine Risikoprüfung die Ursache. Autorisierungs- und Abrechnungsereignisse werden zur Abstimmung auch per Webhook gemeldet.

Verwandte Seiten: Virtuelle Karten · API-Dokumentation · Krypto-Zahlungen über mehrere Blockchains

Wird geladen…