API-Integration

Senden Sie über die Merchant API Auszahlungen von Ihrem Volet.com-Konto an Volet.com-Nutzer und externe Krypto-Wallets.

Mit der Mass Payout API kann Ihre Anwendung Auszahlungstransaktionen programmatisch erstellen, prüfen und verfolgen.

Sie können die API für drei Hauptszenarien nutzen:

• Auszahlungen an Volet.com-Nutzer – Geld von Ihrem Volet.com-Konto an ein anderes Volet.com-Konto senden.
• Krypto-Auszahlungen ohne Umtausch – Kryptowährung aus demselben Krypto-Guthaben an ein externes Krypto-Wallet senden.
• Krypto-Auszahlungen mit Umtausch – Kryptowährung aus einem anderen unterstützten Guthaben, etwa USD, EUR, USDT oder einer anderen Kryptowährung, an ein externes Krypto-Wallet senden.

So funktionieren Massenauszahlungen über die API

Die Merchant API erstellt pro Anfrage eine Auszahlungstransaktion.

Für Massenauszahlungsstapel bereitet Ihr Backend eine Empfängerliste vor und erstellt für jede Position des Stapels eine eigene Auszahlungstransaktion.

Ein typischer Stapelablauf:

1. Bereiten Sie in Ihrem System einen Auszahlungsstapel vor.
2. Prüfen Sie die verfügbaren Guthaben Ihrer Volet.com-Wallets.
3. Prüfen Sie bei Bedarf Limits, Tarife und Wechselkurse.
4. Prüfen Sie jede Auszahlung vor dem Erstellen.
5. Erstellen Sie die Auszahlungstransaktionen über die API.
6. Speichern Sie die zurückgegebenen Transaktions-IDs in Ihrem System.
7. Verfolgen Sie den Auszahlungsstatus über die API.
8. Gleichen Sie abgeschlossene, fehlgeschlagene, stornierte oder erstattete Auszahlungen ab.

Bevor Sie beginnen

Für Massenauszahlungen über die API benötigen Sie:

• Ein verifiziertes Volet.com-Konto.
• Eine konfigurierte API im Bereich Zahlungstools.
• Ausreichend Guthaben auf Ihrem Volet.com-Konto.
• Die für jede Auszahlungsmethode erforderlichen Empfängerdaten.

Unter Massenauszahlungen aktivieren erstellen und konfigurieren Sie Ihre API.

Authentifizierung

Anfragen an die Merchant API erfordern Authentifizierungs-Header.

Senden Sie bei jeder API-Anfrage die folgenden Header mit:

Header	Beschreibung
Api-Name	In Ihrem Volet.com-Konto konfigurierter API-Name.
Account-Email	E-Mail-Adresse des Volet.com-Kontos, zu dem die API gehört.
Authentication-Token	Authentifizierungstoken der Anfrage, erzeugt mit Ihrem API-Secret.

Halten Sie Ihr API-Secret geheim. Legen Sie API-Zugangsdaten oder Authentifizierungstoken niemals in Frontend-Code, mobilen Apps, Bots oder clientseitigen Skripten offen.

Empfohlener Auszahlungsablauf

Vor dem Erstellen von Auszahlungen sollte Ihr Backend jede Position prüfen und vorbereiten.

Empfohlener Ablauf:

1. Wallet-Guthaben abrufen.
2. Mindestlimits für die gewählte Auszahlungsmethode und Währung prüfen.
3. Tarife oder Gebühren prüfen.
4. Wechselkurs prüfen, wenn die Auszahlung einen Umtausch nutzt.
5. Auszahlungsanfrage prüfen.
6. Auszahlungstransaktion erstellen.
7. Zurückgegebene transactionId speichern.
8. Transaktionsstatus abfragen, bis die Auszahlung einen Endstatus erreicht.

Schritt 1: Wallet-Guthaben abrufen

Mit dieser Methode prüfen Sie vor dem Erstellen von Auszahlungen die verfügbaren Guthaben Ihrer Volet.com-Wallets.

Endpunkt:

GET /api/account/balances

Beispielantwort:

[
  {
    "walletId": "W000000000001",
    "amount": 1000.50,
    "currency": "USD"
  },
  {
    "walletId": "W000000000002",
    "amount": 2500,
    "currency": "USDT"
  }
]

Verwenden Sie walletId als Quell-Wallet beim Erstellen von Auszahlungsanfragen.

Schritt 2: Limits und Tarife prüfen

Prüfen Sie vor dem Senden von Auszahlungen die Mindestlimits und Tarife für die gewählte Auszahlungsmethode und das Währungspaar.

Mindestlimits:

GET /api/account/limits/min

Tarife:

GET /api/account/tariffs

Mit diesen Methoden vermeiden Sie Fehler beim Erstellen von Auszahlungen durch nicht unterstützte Beträge, Währungen oder Zahlungsmethoden.

Schritt 3: Wechselkurs prüfen

Nutzen Sie die Wechselkursinformationen, wenn die Auszahlung einen Umtausch erfordert.

Endpunkt:

POST /api/exchange-rate/information

Nutzen Sie dies vor dem Erstellen von Auszahlungen, bei denen Quell- und Auszahlungswährung unterschiedlich sind.

Beispiele:

• USDT aus einem USD-Guthaben an ein externes Krypto-Wallet senden.
• BTC aus einem EUR-Guthaben an ein externes Krypto-Wallet senden.
• Ein unterstütztes Krypto-Guthaben in eine andere Auszahlungswährung umtauschen.

Methode 1: Auszahlungen an Volet.com-Nutzer senden

Nutzen Sie diese Methode, wenn der Empfänger ein Volet.com-Konto hat.

Das Geld wird intern von Ihrem Volet.com-Konto auf das Volet.com-Konto des Empfängers übertragen.

Diese Methode erfordert keine Blockchain-Bestätigung und nutzt keine externen Krypto-Wallet-Adressen.

Auszahlung an einen Volet.com-Nutzer prüfen

Prüfen Sie die Auszahlung, bevor Sie die Transaktion erstellen.

Endpunkt:

POST /api/withdrawal/validation/internal-other

Beispielanfrage:

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

Die Prüfung kontrolliert die Auszahlungsdetails, ohne eine Transaktion zu erstellen.

Auszahlung an einen Volet.com-Nutzer erstellen

Erstellen Sie nach erfolgreicher Prüfung die Auszahlungstransaktion.

Endpunkt:

POST /api/withdrawal/internal-other

Beispielanfrage:

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

Beispielantwort:

{
  "transactionId": "11111111-1111-4111-8111-111111111111",
  "paymentMethodType": "INTERNAL_OTHER",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 25,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.13,
  "comment": "Payout batch 2026-06-26 / recipient 001"
}

Speichern Sie die zurückgegebene transactionId in Ihrem System und verfolgen Sie damit den Auszahlungsstatus.

Optional: Volet.com-Konten der Empfänger prüfen

Wenn Ihr Ablauf die E-Mail-Adressen der Empfänger vor dem Erstellen der Auszahlungen erfasst, können Sie vorab prüfen, ob die Volet.com-Konten existieren.

Endpunkt:

GET /api/account/exists

Wenn Ihr Ablauf zusätzliche Empfängerprüfungen erfordert, können Sie auch die Daten des Kontoinhabers abgleichen.

Endpunkt:

GET /api/account/matching

Mit diesen Methoden verringern Sie fehlgeschlagene Auszahlungen durch falsche Empfängerdaten.

Methode 2: Krypto-Auszahlungen ohne Umtausch senden

Nutzen Sie diese Methode, um Kryptowährung aus demselben Krypto-Guthaben an ein externes Krypto-Wallet zu senden.

Zum Beispiel:

• USDT aus Ihrem USDT-Guthaben an eine externe USDT-TRC-20-Adresse senden.
• BTC aus Ihrem BTC-Guthaben an eine externe BTC-Adresse senden.
• ETH aus Ihrem ETH-Guthaben an eine externe ETH-Adresse senden.

Der Empfänger benötigt kein Volet.com-Konto.

Krypto-Auszahlung ohne Umtausch prüfen

Prüfen Sie die Krypto-Auszahlung, bevor Sie die Transaktion erstellen.

Endpunkt:

POST /api/withdrawal/validation/cryptowallet

Beispielanfrage:

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Verwenden Sie die passende destCurrency für den Auszahlungstoken und das Blockchain-Netzwerk.

Bei Netzwerken, die ein Memo, Destination-Tag oder eine ähnliche Kennung verlangen, geben Sie diese im Feld address.memo an.

Beispiel:

{
  "address": {
    "address": "rXXXXXXXXXXXXXXXXXXXXXXXX",
    "memo": "123456"
  }
}

Krypto-Auszahlung ohne Umtausch erstellen

Erstellen Sie nach erfolgreicher Prüfung die Auszahlungstransaktion.

Endpunkt:

POST /api/withdrawal/cryptowallet

Beispielanfrage:

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Beispielantwort:

{
  "transactionId": "22222222-2222-4222-8222-222222222222",
  "paymentMethodType": "CRYPTO_WALLET",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USDT",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000002",
  "fullCommission": 0.25,
  "comment": "Payout batch 2026-06-26 / recipient 002"
}

Methode 3: Krypto-Auszahlungen mit Umtausch senden

Nutzen Sie diese Methode, wenn Quellguthaben und Auszahlungswährung unterschiedlich sind.

Zum Beispiel:

• USDT aus einem USD-Guthaben an ein externes Wallet senden.
• BTC aus einem EUR-Guthaben an ein externes Wallet senden.
• USDC in einem unterstützten Netzwerk aus einem anderen unterstützten Guthaben senden.

Der Empfänger erhält Kryptowährung in einem externen Krypto-Wallet. Der Umtausch erfolgt im Rahmen des Auszahlungsablaufs.

Krypto-Auszahlung mit Umtausch prüfen

Prüfen Sie die Auszahlung, bevor Sie die Transaktion erstellen.

Endpunkt:

POST /api/withdrawal/validation/crypto-external

Beispielanfrage:

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Mit srcCurrency legen Sie die Währung des Quellguthabens fest, mit destCurrency die an den Empfänger gesendete Kryptowährung und das Netzwerk.

Krypto-Auszahlung mit Umtausch erstellen

Erstellen Sie nach erfolgreicher Prüfung die Auszahlungstransaktion.

Endpunkt:

POST /api/withdrawal/crypto-external

Beispielanfrage:

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Beispielantwort:

{
  "transactionId": "33333333-3333-4333-8333-333333333333",
  "paymentMethodType": "CRYPTO_EXTERNAL",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.50,
  "comment": "Payout batch 2026-06-26 / recipient 003"
}

Felder der Anfrage

Gängige Felder von Auszahlungsanfragen:

Feld	Pflicht	Verwendet für	Beschreibung
srcWalletId	Nein	Alle Auszahlungsmethoden	ID des Quell-Wallets in Ihrem Volet.com-Konto.
amount	Ja	Alle Auszahlungsmethoden	Auszahlungsbetrag. Wie er interpretiert wird, hängt von action ab.
action	Ja	Alle Auszahlungsmethoden	Betragsmodus. Mögliche Werte: GIVE, GET.
note	Nein	Alle Auszahlungsmethoden	Interne Notiz oder Auszahlungsbeschreibung.
srcCurrency	Nein	Auszahlungen an Volet.com-Nutzer, Krypto-Auszahlungen mit Umtausch	Quellwährung der Auszahlung.
destCurrency	Ja	Alle Auszahlungsmethoden	Währung, die dem Empfänger gutgeschrieben oder an das externe Krypto-Wallet gesendet wird.
destEmail	Nein	Auszahlungen an Volet.com-Nutzer	E-Mail-Adresse des Volet.com-Kontos des Empfängers.
destWalletId	Nein	Auszahlungen an Volet.com-Nutzer	Wallet-ID des Empfängers, falls zutreffend.
address.address	Ja	Externe Krypto-Auszahlungen	Krypto-Wallet-Adresse des Empfängers.
address.memo	Nein	Externe Krypto-Auszahlungen	Memo, Destination-Tag oder ähnliche Kennung, falls das gewählte Netzwerk sie verlangt.
receiverInfo	Nein	Externe Krypto-Auszahlungen	Empfängerangaben wie Name, E-Mail, Geburtsdatum oder Firmenname, falls erforderlich.

GIVE und GET

Mit action legen Sie fest, wie der Auszahlungsbetrag interpretiert wird.

Aktion	Bedeutung
GIVE	Der Betrag gilt als der auf der Quellseite zu sendende Betrag.
GET	Der Betrag gilt als der Betrag, den der Empfänger erhalten soll, sofern unterstützt.

Prüfen Sie bei Auszahlungen mit Währungsumtausch vor dem Erstellen den Wechselkurs. So kann Ihr System die erwarteten Quell- und Zielbeträge anzeigen oder speichern, bevor die Transaktion erstellt wird.

Auszahlungsstatus verfolgen

Speichern Sie nach dem Erstellen einer Auszahlung die zurückgegebene transactionId.

Rufen Sie mit der Transaktionsabfrage den aktuellen Auszahlungsstatus ab.

Endpunkt:

GET /api/transactions/{id}

Sie können auch den Transaktionsverlauf durchsuchen.

Endpunkt:

GET /api/transactions

Nützliche Filter:

Filter	Beschreibung
paymentDirections	Nach DEPOSIT oder WITHDRAWAL filtern.
transactionStatus	Nach Transaktionsstatus filtern.
wallets	Nach Wallet-IDs filtern.
startDate / endDate	Nach Erstellungszeitraum filtern.
searchLabel	Nach Textlabel suchen, falls zutreffend.
offset / limit	Ergebnisse paginieren.
sortOrder	Ergebnisse nach Erstellungsdatum sortieren.

Transaktionsstatus

Aktualisieren Sie anhand des Transaktionsstatus den Auszahlungsstatus in Ihrem eigenen System.

Status	Bedeutung	Empfohlene Aktion
CREATED	Die Auszahlungstransaktion wurde erstellt.	Transaktion speichern und weiter verfolgen.
READY_TO_PROCESS	Die Auszahlung ist zur Verarbeitung bereit.	Weiter verfolgen.
PENDING	Die Auszahlung ist ausstehend.	Weiter verfolgen.
PROCESSING	Die Auszahlung wird verarbeitet.	Weiter verfolgen.
EXCHANGING	Der Währungsumtausch läuft.	Weiter verfolgen.
COMPLETED	Die Auszahlung ist abgeschlossen.	Auszahlung in Ihrem System als abgeschlossen markieren.
CANCELLING	Die Stornierung läuft.	Auf den Endstatus warten.
CANCELED	Die Auszahlung wurde storniert.	Auszahlung als storniert markieren.
REFUNDING	Die Erstattung läuft.	Auf den Endstatus warten.
REFUNDED	Die Auszahlung wurde erstattet.	Auszahlung als erstattet markieren.

Behandeln Sie die Auszahlung erst als abgeschlossen, wenn der Status COMPLETED lautet.

Auszahlungen stornieren

Manche Transaktionen lassen sich stornieren, solange eine Stornierung noch zulässig ist.

Endpunkt:

DELETE /api/transactions/{transactionId}

Ob eine Stornierung möglich ist, hängt von Auszahlungsmethode, Transaktionsstatus und Verarbeitungsphase ab.

Verlassen Sie sich bei Krypto-Auszahlungen nicht auf eine Stornierung, nachdem die Blockchain-Transaktion gesendet wurde. Prüfen Sie alle Empfängeradressen, Währungen, Netzwerke und Beträge, bevor Sie die Auszahlung erstellen.

Empfehlungen für die Stapelverarbeitung

Bei Massenauszahlungen sollte Ihr Backend den Lebenszyklus des Stapels steuern.

Empfohlenes Vorgehen:

1. Vergeben Sie eine interne Stapel-ID.
2. Vergeben Sie für jede Auszahlung eine interne Positions-ID.
3. Prüfen Sie jede Position, bevor Sie Transaktionen erstellen.
4. Erstellen Sie Transaktionen nur für geprüfte Positionen.
5. Speichern Sie die Zuordnung zwischen Ihrer internen Positions-ID und der zurückgegebenen transactionId.
6. Verfolgen Sie jede Transaktion einzeln.
7. Wiederholen Sie nur fehlgeschlagene oder nicht erstellte Positionen.
8. Gleichen Sie die Endstatus ab, bevor Sie den Stapel als abgeschlossen markieren.

Vermeiden Sie doppelte Auszahlungen. Wiederholt Ihre Anwendung eine Anfrage nach einem Timeout, prüfen Sie zuerst, ob für diese Position bereits eine Transaktion erstellt wurde.

Fehlerbehandlung

Fehler der Merchant API liefern strukturierte Fehlerantworten.

Häufige Fehlerfälle:

HTTP-Status	Bedeutung
400	Die Anfrage ist fehlerhaft oder enthält ungültige Parameter.
401	Authentifizierungs-Header fehlen oder sind ungültig.
403	Die API hat keine Berechtigung für den angeforderten Vorgang.
404	Die angeforderte Ressource wurde nicht gefunden.
500	Unerwarteter Serverfehler.

Bei einem Fehler:

• Protokollieren Sie errorId für Support und Diagnose.
• Prüfen Sie errorField, um das betroffene Feld der Anfrage zu ermitteln.
• Erstellen Sie nicht automatisch eine Ersatzauszahlung, bevor Sie sichergestellt haben, dass keine Transaktion erstellt wurde.
• Wiederholen Sie die Anfrage nur, wenn das gefahrlos möglich ist.

Test-Checkliste

Testen Sie den gesamten Ablauf, bevor Sie echte Massenauszahlungen senden.

Für Auszahlungen an Volet.com-Nutzer:

• Prüfung des Empfängerkontos.
• Prüfung der Auszahlung.
• Erstellung der Auszahlung.
• Verfolgung des Transaktionsstatus.
• Abgeschlossene, stornierte und fehlgeschlagene Szenarien.

Für Krypto-Auszahlungen ohne Umtausch:

• Korrekte Auswahl von Token und Netzwerk.
• Behandlung von Adresse und Memo.
• Prüfung der Auszahlung.
• Erstellung der Auszahlung.
• Verfolgung der Blockchain-Transaktion.
• Behandlung falscher Adressen oder nicht unterstützter Netzwerke.

Für Krypto-Auszahlungen mit Umtausch:

• Guthabenprüfung.
• Wechselkursprüfung.
• Prüfung der Auszahlung.
• Erstellung der Auszahlung.
• Status EXCHANGING und COMPLETED.
• Abgleich der Beträge zwischen Quell- und Zielwährung.

Für die Stapelverarbeitung:

• Behandlung teilweise fehlgeschlagener Stapel.
• Wiederholungslogik.
• Vermeidung von Duplikaten.
• Interne Zuordnung von Stapeln zu Transaktionen.
• Abschließender Abgleichsbericht.

Wichtige Hinweise

• Die API erstellt pro Anfrage eine Auszahlungstransaktion.
• Für die Steuerung der Stapel ist Ihr Backend verantwortlich.
• Prüfen Sie Auszahlungen immer, bevor Sie Transaktionen erstellen.
• Speichern Sie immer die zurückgegebenen transactionId-Werte.
• Verfolgen Sie den Endstatus über die Transaktionsabfrage oder den Transaktionsverlauf.
• Markieren Sie eine Auszahlung erst als abgeschlossen, wenn der Status COMPLETED lautet.
• Prüfen Sie bei Krypto-Auszahlungen vor dem Erstellen der Transaktion immer Adresse, Token, Netzwerk und Memo des Empfängers.
• Wird Krypto an eine falsche Adresse oder über ein falsches Netzwerk gesendet, kann es dauerhaft verloren gehen.
• API-Zugangsdaten dürfen niemals im Frontend-Code offengelegt werden.

Siehe auch

• Massenauszahlungen aktivieren — API vor dem Senden von Auszahlungen einrichten
• Auszahlungen an Volet.com-Nutzer senden — interne Auszahlungen an Volet.com-Konten senden
• Custodial-Krypto-Auszahlungen senden — Krypto von Ihrem Volet.com-Konto an externe Wallets senden
• Massenauszahlungen im Überblick — Auszahlungsmethoden und -modelle vergleichen
• API-Referenz — vollständige Dokumentation der Methoden, Parameter und Antworten