API-Integration

Akzeptieren Sie Krypto-Zahlungen aus externen Krypto-Wallets über die Merchant API.

Bei der API-Integration erstellt Ihre Anwendung Krypto-Rechnungen, zeigt Kunden die Zahlungsanweisungen an und verfolgt den Zahlungsstatus über die API.

Sie können die API auf zwei Arten nutzen:

• Nur API – Ihre Anwendung baut das gesamte Zahlungserlebnis auf und zeigt dem Kunden Krypto-Adresse, Betrag, Netzwerk und Ablaufzeit an.
• API + Hosted Checkout – Ihr Backend nutzt die API für Bestellverfolgung und Abgleich, Hosted Checkout stellt die Zahlungsseite für den Kunden bereit.

Wann sich die API-Integration eignet

Nutzen Sie die API-Integration, wenn Sie den Zahlungsablauf in Ihrer eigenen Website, App, Ihrem Bot oder KI-Agenten steuern möchten.

Die API-Integration ist sinnvoll, wenn:

• Sie Ihre eigene Checkout-Oberfläche bauen möchten.
• Sie Krypto-Rechnungen programmatisch erstellen müssen.
• Sie Zahlungsanweisungen in Ihrem eigenen Produkt anzeigen möchten.
• Sie den Zahlungsstatus aus Ihrem Backend verfolgen müssen.
• Sie Hosted Checkout mit einem Bestellabgleich im Backend kombinieren möchten.

Für die schnellste Integration mit einer fertigen Zahlungsseite nutzen Sie stattdessen die Hosted-Checkout-Integration.

Integrationsmodelle

Modell	Kundenerlebnis	Aufgabe des Backends	Statusverarbeitung
Nur API	Von Ihrer Anwendung erstellt	Rechnung erstellen, Zahlungsdetails anzeigen, Status verfolgen	Zahlungsstatus regelmäßig über die API abfragen
API + Hosted Checkout	Von Volet.com gehostet	Bestellungen erstellen oder verfolgen, Zahlungsstatus abgleichen	Status URL von Hosted Checkout und Bestellabfrage per API nutzen

Bevor Sie beginnen

Um Krypto-Zahlungen über die API anzunehmen, benötigen Sie:

• Ein verifiziertes Volet.com-Konto.
• Eine konfigurierte API im Bereich Zahlungstools.
• API-Berechtigungen für die Annahme von Krypto-Zahlungen.
• Eine Hosted-Checkout-Konfiguration, wenn Sie die API zusammen mit Hosted Checkout nutzen.

Unter Zahlungs-Gateway erstellen erfahren Sie, wie Sie Ihre API erstellen und konfigurieren.

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.

Ablauf nur mit API

Nutzen Sie diesen Ablauf, wenn Ihre Anwendung das gesamte Krypto-Zahlungserlebnis übernimmt.

Der Zahlungsablauf:

1. Legen Sie in Ihrem System eine Bestellung an.
2. Prüfen Sie optional die Rechnungsdetails vor dem Erstellen.
3. Erstellen Sie über die API eine Krypto-Rechnung.
4. Zeigen Sie dem Kunden Zahlungsadresse, Betrag, Währung, Netzwerk und Ablaufzeit an.
5. Der Kunde sendet die Zahlung aus einem Krypto-Wallet.
6. Ihr Backend fragt den Zahlungsstatus über die API ab.
7. Ist die Zahlung abgeschlossen, aktualisieren Sie den Bestellstatus in Ihrem System.

Schritt 1: Rechnungsdetails prüfen

Vor dem Erstellen einer Rechnung können Sie die berechneten Werte prüfen.

In diesem Schritt sehen Sie Absenderbetrag, Empfängerbetrag, Währungsumrechnung und Ablaufzeit, bevor Sie die eigentliche Rechnung erstellen.

Endpunkt:

POST /api/invoice/crypto-invoice/check

Beispielanfrage:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com"
}

Beispielantwort:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com",
  "senderAmount": 100,
  "receiverAmount": 100,
  "expirationDate": "2026-01-15T10:30:00",
  "expirationDateMillis": 1768473000000
}

Dieser Schritt erstellt keine Zahlungsadresse und startet keine Zahlung.

Schritt 2: Krypto-Rechnung erstellen

Erstellen Sie eine Krypto-Rechnung, sobald der Kunde zahlungsbereit ist.

Endpunkt:

POST /api/invoice/crypto-invoice/deposit

Beispielanfrage:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com"
}

Die Antwort enthält die Zahlungsdetails, die Ihre Anwendung dem Kunden anzeigen soll.

Beispielantwort:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com",
  "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "addressOldFormat": null,
  "destinationTag": null,
  "senderAmount": 100,
  "receiverAmount": 100,
  "expirationDate": "2026-01-15T10:30:00",
  "expirationDateMillis": 1768473000000
}

Felder der Rechnungsanfrage

Feld	Pflicht	Beschreibung
receiverCurrency	Ja	Währung, die nach Abschluss der Zahlung Ihrem Volet.com-Konto gutgeschrieben wird.
senderCurrency	Ja	Währung und Netzwerk, mit denen der Kunde bezahlen soll.
amount	Ja	Zahlungsbetrag. Wie er interpretiert wird, hängt von transferAction ab.
transferAction	Ja	Legt fest, ob der Betrag als zu sendender oder als zu empfangender Betrag gilt. Mögliche Werte: GIVE, GET.
note	Nein	Zahlungsnotiz oder Bestellbeschreibung.
sciName	Nein	Name des Hosted Checkout oder Shops, der dem Zahlungsablauf zugeordnet ist.
orderId	Nein	Ihre interne Bestell-ID. Verwenden Sie für jede Zahlung einen eindeutigen Wert.
subMerchantURL	Nein	Website-URL des Sub-Händlers, wenn die Zahlung im Namen eines anderen Händlers abgewickelt wird.

Felder der Rechnungsantwort

Feld	Beschreibung
address	Krypto-Adresse, an die der Kunde die Zahlung senden soll.
addressOldFormat	Alternatives Adressformat, sofern für das gewählte Netzwerk verfügbar.
destinationTag	Destination-Tag, Memo oder zusätzliche Kennung, die manche Netzwerke verlangen.
senderAmount	Betrag, den der Kunde senden soll.
senderCurrency	Währung und Netzwerk, die der Kunde verwenden soll.
receiverAmount	Betrag, der voraussichtlich Ihrem Konto gutgeschrieben wird.
receiverCurrency	Währung, die Ihrem Konto gutgeschrieben wird.
expirationDate	Ablaufdatum und -uhrzeit der Rechnung.
expirationDateMillis	Ablaufzeitpunkt der Rechnung in Millisekunden.

Zeigen Sie senderAmount, senderCurrency, address und – falls zurückgegeben – destinationTag immer exakt an.

Schritt 3: Zahlungsanweisungen anzeigen

Im Modus „Nur API“ ist Ihre Anwendung dafür verantwortlich, dem Kunden die Zahlungsanweisungen anzuzeigen.

Zeigen Sie mindestens an:

• Den zu sendenden Betrag.
• Währung und Blockchain-Netzwerk.
• Die Krypto-Adresse.
• Destination-Tag oder Memo, falls erforderlich.
• Die Ablaufzeit.
• Einen Hinweis, Geld nur über das ausgewählte Netzwerk zu senden.

Beispielanweisung:

Send exactly 100 USDT on Tron (TRC-20) to:

TXXXXXXXXXXXXXXXXXXXXXXXXXXXX

This invoice expires at 2026-01-15 10:30 UTC.
Do not send funds on another network.

Bei Netzwerken, die ein Destination-Tag oder Memo verlangen, zeigen Sie es gut sichtbar neben der Adresse an.

Schritt 4: Zahlungsstatus abfragen

Nach dem Erstellen der Rechnung sollte Ihr Backend den Zahlungsstatus abfragen.

Endpunkt:

GET /api/orders

Erforderlicher Query-Parameter:

Parameter	Beschreibung
orderId	Bestellkennung des Händlers.

Optionaler Query-Parameter:

Parameter	Beschreibung
sciName	Name des Hosted Checkout oder Shops, der der Bestellung zugeordnet ist.

Beispielanfrage:

GET /api/orders?orderId=ORDER-1001&sciName=Store

Beispielantwort:

{
  "orderId": "ORDER-1001",
  "sciName": "Store",
  "paymentStatus": "PROCESSING",
  "paymentMethod": "CRYPTO_INVOICE",
  "paymentCreated": "2026-01-15T10:30:00",
  "transaction": {
    "status": "PROCESSING"
  },
  "invoice": {
    "invoiceStatus": "PROCESSING",
    "cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "initialSenderAmount": 100,
    "actualReceivedAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
  }
}

Zahlungsstatus

Entscheiden Sie anhand von paymentStatus, wie Sie die Bestellung in Ihrem System aktualisieren.

Status	Bedeutung	Empfohlene Aktion
CREATED	Die Rechnung wurde erstellt und wartet auf die Zahlung.	Bestellung offen lassen.
PROCESSING	Die Zahlung wurde erkannt oder wird verarbeitet.	Bestellung offen lassen und weiter abfragen.
COMPLETED	Die Zahlung wurde erfolgreich abgeschlossen.	Bestellung als bezahlt markieren und Ware oder Leistung liefern.
FAILED	Die Zahlung ist fehlgeschlagen, abgelaufen oder konnte nicht abgeschlossen werden.	Bestellung nicht ausliefern. Den Kunden um eine neue Zahlung bitten.

Behandeln Sie die Bestellung erst als bezahlt, wenn der Status COMPLETED lautet.

Ablauf API + Hosted Checkout

Nutzen Sie dieses Modell, wenn Hosted Checkout die Zahlungsseite für den Kunden übernehmen soll, Ihr Backend aber per API die Kontrolle über Bestellverfolgung und Abgleich behält.

Der Zahlungsablauf:

1. Legen Sie in Ihrem System eine Bestellung an.
2. Leiten Sie den Kunden über Ihre Hosted-Checkout-Integration zu Hosted Checkout weiter.
3. Übergeben Sie Ihre orderId in der Hosted-Checkout-Zahlungsanfrage.
4. Der Kunde schließt die Zahlung auf der Hosted-Checkout-Seite ab.
5. Volet.com sendet eine Benachrichtigung zum Zahlungsstatus an Ihre Status URL.
6. Ihr Backend prüft die Signatur der Benachrichtigung.
7. Ihr Backend aktualisiert den Bestellstatus.
8. Optional fragt Ihr Backend die Bestellung zum Abgleich zusätzlich über die API ab.

In diesem Modell übernimmt Hosted Checkout die Zahlungsseite, die Auswahl der Zahlungsmethode, die Zahlungsanweisungen und die Kundenweiterleitungen.

Über die API können Sie den Zahlungsauftrag weiterhin anhand der orderId abrufen und den endgültigen Status in Ihrem System abgleichen.

Statusverarbeitung mit Hosted Checkout

Verlassen Sie sich bei Hosted Checkout nicht allein auf die Weiterleitungen zur Success URL oder Failed URL.

Kundenweiterleitungen sind Teil des Browserablaufs und erreichen Ihren Server nicht immer. Nutzen Sie die Benachrichtigung an die Status URL und die Bestellabfrage per API, um den Bestellstatus zuverlässig zu aktualisieren.

Empfohlenes Vorgehen:

1. Empfangen Sie die Hosted-Checkout-Benachrichtigung an der Status URL.
2. Prüfen Sie die Signatur der Benachrichtigung.
3. Aktualisieren Sie den Bestellstatus, wenn die Benachrichtigung gültig ist.
4. Nutzen Sie die Bestellabfrage per API als Fallback oder zum Abgleich.

Fehlerbehandlung

Fehler der Merchant API liefern eine strukturierte Fehlerantwort.

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.
• Legen Sie nicht automatisch eine doppelte Bestellung an.
• Wiederholen Sie die Anfrage nur, wenn das gefahrlos möglich ist.

Test-Checkliste

Testen Sie den gesamten Ablauf, bevor Sie echte Krypto-Zahlungen annehmen.

Prüfen Sie bei Integrationen nur mit API:

• Rechnungsprüfung.
• Rechnungserstellung.
• Anzeige der Zahlungsadresse.
• Anzeige von Destination-Tag oder Memo, falls erforderlich.
• Behandlung abgelaufener Rechnungen.
• Regelmäßige Abfrage des Bestellstatus.
• Behandlung abgeschlossener Zahlungen.
• Behandlung fehlgeschlagener oder abgelaufener Zahlungen.
• Behandlung doppelter orderId-Werte.

Prüfen Sie bei Integrationen mit API + Hosted Checkout zusätzlich:

• Weiterleitung des Kunden zu Hosted Checkout.
• Zustellung der Benachrichtigungen an die Status URL.
• Prüfung der Signatur von Benachrichtigungen.
• Weiterleitungen zur Success URL und Failed URL.
• Bestellabfrage per API für den Abgleich.

Wichtige Hinweise

• Integrationen nur mit API nutzen keine Hosted-Checkout-Callbacks.
• Ihr Backend sollte den Zahlungsstatus über die API abfragen.
• Verwenden Sie für jede Zahlung eine eindeutige orderId.
• Zeigen Sie Adresse, Betrag, Währung, Netzwerk und Destination-Tag immer genau so an, wie die API sie zurückgibt.
• Markieren Sie eine Bestellung erst als bezahlt, wenn der Zahlungsstatus COMPLETED lautet.
• Krypto-Zahlungen hängen von Blockchain-Bestätigungen und Netzwerkbedingungen ab.
• Wird Geld an eine falsche Adresse oder über ein falsches Netzwerk gesendet, kann es dauerhaft verloren gehen.

Siehe auch

• Zahlungs-Gateway erstellen — API erstellen und konfigurieren
• Custodial-Krypto-Zahlungen akzeptieren — so funktionieren Custodial-Krypto-Zahlungen
• Hosted-Checkout-Integration — die gehostete Zahlungsseite nutzen
• API-Referenz — vollständige Dokumentation der Methoden, Parameter und Antworten