Feldkonventionen & Glossar
| Header | Erforderlich | Definition |
|---|
| x-api-key | Ja | In der App ("Business") ausgestellter API-Key. Die Organisation wird anhand des Anfrage-Hosts ermittelt |
| Content-Type | Ja (POST) | application/json für Erstellungsanfragen |
Betrag & Währung
| Begriff | Definition |
|---|
| amount | String einer Ganzzahl in kleinsten Einheiten |
| amount_with_fee | Betrag inkl. Gebühr |
| currency | Währungs-/Token-Code (USDT) |
| currency_dest | Zielwährung für Konvertierung (FX). Optional; Standard ist currency |
Bezeichner
| Begriff | Definition |
|---|
| id | Interne Transaktions-UUID |
| txid | Idempotente externe Kunden-ID. Muss bei Angabe eine gültige UUID sein; kann weggelassen werden |
Routing & Umgebung
| Begriff | Definition |
|---|
| route | Verarbeitungsalias (konfiguriert für API-Key) |
| env | Umgebung: prod (Default) oder test |
Status
| Status | Bedeutung |
|---|
| created | Angenommen, wartet |
| new | Anfangszustand vor Verarbeitungsbeginn |
| authorizing | Autorisierung läuft |
| pre_authorized_3ds | Wartet auf 3DS-Authentifizierung |
| action_required | Zusätzliche Aktion erforderlich (3DS / weitere Autorisierung) |
| charging | In Verarbeitung |
| payment_suspended | Eingehende Transaktion vorübergehend ausgesetzt |
| payout_suspended | Ausgehende Transaktion vorübergehend ausgesetzt |
| charged | Erfolgreich abgeschlossen (terminal) |
| reversed | Buchung storniert (terminal) |
| refunded | Erstattet (terminal) |
| rejected | Abgelehnt (terminal) |
| failed | Fehlgeschlagen (terminal) |
Terminale Status: charged, reversed, refunded, rejected, failed. Typischer Happy-Path: created → charging → charged.
Zeitfelder
| Feld | Bedeutung |
|---|
| started | Startzeit (ISO) |
| finished | Abschlusszeit (ISO) |
money_storage Felder
| Feld | Bedeutung |
|---|
| network | Blockchain-Netzwerk |
| type | Instrumenttyp |
| wallet_id | Wallet-ID |
| cardnumber | Virtuelle Kartennummer |
| cvv | Virtueller Karten-CVV |
| exp_month / exp_year | Ablaufdaten |
| cardholder | Karteninhaber |
Fehler
| Feld | Bedeutung |
|---|
| error_description | Fehlertext (nicht stabil) |
Idempotenz
Verwenden Sie einen eindeutigen txid (gültige UUID) pro Geschäftsvorgang. Erstellungsanfragen nur mit identischem txid wiederholen — eine Wiederholung gibt die bereits erstellte Transaktion zurück, statt eine neue zu erzeugen. Ein nicht-UUID txid wird mit 422 invalid_txid abgelehnt.
Polling
Intervalle: 1s, 2s, 4s, 8s … bis charged oder rejected.
Webhook
Informativ – Status immer per GET verifizieren.