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 oder über Benachrichtigungen an die Status URL.

Sie können die API auf drei Arten nutzen:

Nur API mit Statusabfrage – Ihre Anwendung baut das gesamte Zahlungserlebnis auf und fragt den Zahlungsstatus über die API ab.
Nur API mit Benachrichtigungen an die Status URL – Ihre Anwendung baut das gesamte Zahlungserlebnis auf, eine Hosted-Checkout-Konfiguration liefert die Status URL für Zahlungsbenachrichtigungen. Die Hosted-Checkout-Seite selbst wird nicht verwendet.
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 Benachrichtigungen zum Zahlungsstatus auf Ihrem Server empfangen möchten.
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 + Abfrage	Von Ihrer Anwendung erstellt	Rechnung erstellen, Zahlungsdetails anzeigen, Status verfolgen	`GET /api/orders` regelmäßig abfragen
Nur API + Status URL	Von Ihrer Anwendung erstellt	Rechnung erstellen, Zahlungsdetails anzeigen, Benachrichtigungen verarbeiten	Status URL von Hosted Checkout, Abfrage per API für den Abgleich
API + Hosted Checkout	Von Volet.com gehostet	Bestellungen verfolgen und Zahlungsstatus abgleichen	Status URL von Hosted Checkout, Abfrage per API für den Abgleich

Bevor Sie beginnen

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

Ein verifiziertes Volet.com-Konto.
Eine konfigurierte API im Bereich Zahlungstools.
Die folgenden API-Berechtigungen:
- Transaktionen ausführen → Krypto-Zahlungen akzeptieren – zum Erstellen von Krypto-Rechnungen.
- Transaktion suchen – zum Abrufen von Zahlungsaufträgen.
Eine Hosted-Checkout-Konfiguration, deren Namen Sie als sciName übergeben können.

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

Aktuelle Anforderung an sciName

Die aktuelle Implementierung von GET /api/orders benötigt den Namen eines Hosted Checkout (sciName), um eine Bestellung abzurufen.

Solange diese Anforderung besteht, erstellen Sie eine Hosted-Checkout-Konfiguration und übergeben Sie deren Namen als sciName, wenn Sie Krypto-Rechnungen erstellen, die Sie verfolgen müssen.

Sie müssen Kunden nicht auf die Hosted-Checkout-Seite weiterleiten. Die Konfiguration kann allein dazu dienen, den erforderlichen sciName und optional Benachrichtigungen an die Status URL bereitzustellen.

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`	SHA-256-Token, erzeugt aus `password:YYYYMMDD:HH` (UTC), wobei das Passwort in Ihrem Volet.com-Konto unter Zahlungstools festgelegt wird.

Beispiel:

SHA256("MySecret123:20261026:14")

ergibt:

c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd

Der Tokenwert ändert sich zu jeder vollen Stunde (UTC). Erzeugen Sie unmittelbar vor jeder Anfrage ein neues Token, damit Sie kein Token aus der vorherigen Stunde wiederverwenden.

An die API wird nur das erzeugte Token gesendet. Senden Sie niemals Ihr API-Passwort.

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

Beispiel einer authentifizierten Anfrage:

curl -X POST https://api.volet.com/api/invoice/crypto-invoice/deposit \
  -H "Content-Type: application/json" \
  -H "Api-Name: my-store-api" \
  -H "Account-Email: [email protected]" \
  -H "Authentication-Token: c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd" \
  -d '{
    "receiverCurrency": "USD",
    "senderCurrency": "USDT_TRC20",
    "amount": 100,
    "transferAction": "GET",
    "sciName": "Store",
    "orderId": "ORDER-1001"
  }'

Zahlungsablauf nur mit API

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

Legen Sie in Ihrem System eine Bestellung an.
Prüfen Sie optional die berechneten Rechnungsdetails.
Erstellen Sie über die API eine Krypto-Rechnung.
Zeigen Sie dem Kunden Zahlungsadresse, Betrag, Währung, Netzwerk und Ablaufzeit an.
Der Kunde sendet die Zahlung aus einem Krypto-Wallet.
Verfolgen Sie die Zahlung über GET /api/orders, über Benachrichtigungen an die Status URL oder beides.
Ist die Zahlung abgeschlossen, aktualisieren Sie den Bestellstatus in Ihrem System.

Schritt 1 (optional): 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

Siehe Krypto-Rechnung prüfen in der API-Referenz.

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

Siehe Krypto-Rechnung zur Aufladung erstellen in der API-Referenz.

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
}

Die Beträge in diesen Beispielen dienen nur zur Veranschaulichung. Die tatsächlichen Werte von senderAmount und receiverAmount hängen von den gewählten Währungen, dem Wechselkurs und den anfallenden Gebühren ab.

Felder der Rechnungsanfrage

Feld	Pflicht	Beschreibung
`receiverCurrency`	Ja	Währung, die nach Abschluss der Zahlung Ihrem Volet.com-Konto gutgeschrieben wird. Unterstützte Werte finden Sie in der API-Referenz.
`senderCurrency`	Ja	Währung und Netzwerk, mit denen der Kunde bezahlen soll, zum Beispiel `USDT_TRC20`.
`amount`	Ja	Zahlungsbetrag. Wie er interpretiert wird, hängt von `transferAction` ab.
`transferAction`	Ja	Legt fest, auf welche Seite sich `amount` bezieht. Mögliche Werte: `GIVE`, `GET`. Siehe `GIVE` und `GET`.
`note`	Nein	Zahlungsnotiz oder Bestellbeschreibung. Bis zu 255 Zeichen.
`sciName`	Nein*	In Ihrem Volet.com-Konto festgelegter Name des Hosted Checkout. Derzeit erforderlich, wenn Sie die Bestellung über `GET /api/orders` abrufen oder Benachrichtigungen an die Status URL über die Hosted-Checkout-Konfiguration erhalten möchten.
`orderId`	Nein*	Ihre interne Bestell-ID, bis zu 64 Zeichen. Erforderlich, um die Zahlung später mit `GET /api/orders` abzurufen. 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. Siehe Sub-Händler.

* Der Endpunkt zum Erstellen von Rechnungen akzeptiert das Feld möglicherweise als optional, für die in dieser Anleitung beschriebenen Verfolgungsabläufe ist es jedoch erforderlich.

`GIVE` und `GET`

transferAction bestimmt, in welcher Währung der amount der Anfrage angegeben ist.

Wert	Bedeutung von `amount`
`GIVE`	Der Betrag, den der Kunde sendet, in `senderCurrency`.
`GET`	Der Betrag, der Ihrem Volet.com-Konto gutgeschrieben werden soll, in `receiverCurrency`.

Die von der API zurückgegebenen endgültigen Werte von senderAmount und receiverAmount können aufgrund von Wechselkursen und anfallenden Gebühren abweichen.

Währungscodes

Einige Kryptowährungscodes enthalten nach einem Unterstrich das Blockchain-Netzwerk.

Beispiele:

USDT_TRC20 – USDT auf Tron.
USDT_ERC20 – USDT auf Ethereum.
USDC_SOL – USDC auf Solana.

Andere Assets verwenden einen einzelnen Währungscode, etwa BTC, ETH oder TON.

Zulässige Werte finden Sie unter Unterstützte Währungen und Tokens und in der API-Referenz.

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 voraussichtlich Ihrem Konto gutgeschrieben wird.
`expirationDate`	Ablaufdatum und -uhrzeit der Rechnung.
`expirationDateMillis`	Ablaufzeitpunkt der Rechnung als Unix-Zeitstempel in Millisekunden.

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

Berechnen und zeigen Sie den Ablaufzeitpunkt der Rechnung anhand von expirationDateMillis 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.

Beispiel:

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 kann Ihr Backend den Zahlungsauftrag über die API abrufen.

Endpunkt:

GET /api/orders

Siehe Zahlungsauftrag abrufen in der API-Referenz.

Aktuelle Query-Parameter:

Parameter	Pflicht	Beschreibung
`orderId`	Ja	Bestellkennung des Händlers, bis zu 64 Zeichen.
`sciName`	Ja*	Name des Hosted Checkout, der der Rechnung zugeordnet ist.

* sciName wird derzeit von der API-Implementierung beim Abrufen einer Bestellung verlangt.

Beispielanfrage:

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

Vorläufige Lösung für sciName

Derzeit lässt sich eine per API erstellte Bestellung nicht zuverlässig allein über die orderId abrufen.

Erstellen Sie eine Hosted-Checkout-Konfiguration, verwenden Sie deren Namen beim Erstellen der Krypto-Rechnung als sciName und übergeben Sie denselben Wert an GET /api/orders.

Diese Lösung funktioniert, ohne dass dem Kunden die Hosted-Checkout-Seite angezeigt wird.

Beispielantwort:

{
  "orderId": "ORDER-1001",
  "sciName": "Store",
  "paymentStatus": "PENDING",
  "paymentMethod": "CRYPTO_INVOICE",
  "paymentCreated": "2026-01-15T10:00:00",
  "transaction": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "PENDING",
    "senderAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "receiverAmount": 100,
    "receiverCurrency": "USD",
    "created": "2026-01-15T10:00:00"
  },
  "invoice": {
    "created": "2026-01-15T10:00:00",
    "received": "2026-01-15T10:12:00",
    "invoiceStatus": "RECEIVED",
    "externalStatus": "PAYMENT_RECEIVED",
    "penalties": [],
    "cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "initialSenderAmount": 100,
    "actualReceivedAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
  }
}

Wird keine passende Bestellung gefunden, kann die API 404 zurückgeben. Prüfen Sie orderId und sciName, bevor Sie für dieselbe Bestellung eine weitere Rechnung erstellen.

Zahlungsstatus

Ob die Zahlung abgeschlossen ist, erkennen Sie am paymentStatus auf oberster Ebene.

Status	Bedeutung	Empfohlene Aktion
`PENDING`	Die Zahlung hat noch keinen endgültigen abgeschlossenen Zustand erreicht.	Bestellung offen lassen.
`COMPLETED`	Die Zahlung wurde erfolgreich abgeschlossen.	Bestellung als bezahlt markieren und Ware oder Leistung liefern.
`CANCELED`	Die Zahlung wurde storniert.	Bestellung nicht ausführen.
`REFUNDED`	Die Zahlung wurde erstattet.	Bestellung gemäß Ihrem Erstattungsprozess aktualisieren.

Behandeln Sie eine Bestellung erst als bezahlt, wenn paymentStatus den Wert COMPLETED hat.

Die Antwort enthält außerdem rechnungsspezifische Felder wie invoiceStatus, externalStatus und penalties. Sie können zusätzliche Informationen zur Krypto-Rechnung liefern.

Leiten Sie den endgültigen Bestellstatus nicht aus undokumentierten Werten von externalStatus oder penalties ab. Verwenden Sie sie nur, wenn Ihre Integration die von der API zurückgegebenen Werte ausdrücklich verarbeitet.

cryptoCurrencyTransactionId ist die von der API zurückgegebene Kennung der Krypto-Transaktion. Gehen Sie nicht davon aus, dass es sich dabei um einen Blockchain-Transaktions-Hash handelt, solange das für den gewählten Zahlungsablauf nicht bestätigt ist.

Benachrichtigungen an die Status URL empfangen

Die regelmäßige Abfrage von GET /api/orders ist nicht die einzige Möglichkeit, per API erstellte Krypto-Rechnungen zu verfolgen.

Die API-Konfiguration in Ihrem Volet.com-Konto bietet derzeit keine Felder für Webhook-URLs. Sie können jedoch die für ein Hosted-Checkout-Gateway konfigurierte Status URL nutzen, um Benachrichtigungen zum Zahlungsstatus für per API erstellte Rechnungen zu empfangen.

Bei diesem Ablauf müssen Sie Kunden Hosted Checkout weder anzeigen noch sie dorthin weiterleiten.

Benachrichtigungen an die Status URL einrichten

Erstellen Sie in Ihrem Volet.com-Konto eine Hosted-Checkout-Konfiguration.
Legen Sie deren Status URL fest und wählen Sie die gewünschte HTTP-Methode.
Verwenden Sie den Namen des Hosted Checkout als sciName, wenn Sie Krypto-Rechnungen über die API erstellen.
Belassen Sie den Zahlungsablauf für den Kunden in Ihrer eigenen Anwendung.
Ändert sich der Zahlungsstatus, sendet Volet.com eine Benachrichtigung an die für diesen Hosted Checkout konfigurierte Status URL.
Prüfen Sie die Signatur der Benachrichtigung, bevor Sie die Bestellung in Ihrem System aktualisieren.
Nutzen Sie GET /api/orders bei Bedarf zum Abgleich oder als Fallback.

Beispiel einer Rechnungsanfrage:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001"
}

In diesem Beispiel ist Store der Name der Hosted-Checkout-Konfiguration, die die Status URL enthält.

Der Kunde sieht weiterhin Ihre eigene Zahlungsoberfläche. Die Hosted-Checkout-Zahlungsseite wird nicht geöffnet.

hinweis

Derselbe sciName erfüllt in einer Integration nur mit API also zwei Aufgaben:

Er ermöglicht der aktuellen Implementierung von GET /api/orders, die Bestellung zu finden.
Er verknüpft die per API erstellte Rechnung mit der Hosted-Checkout-Konfiguration, über die Benachrichtigungen an die Status URL laufen.

Parameter der Benachrichtigungen und die Signaturprüfung finden Sie unter Hosted-Checkout-Integration.

Abfrage und Benachrichtigungen an die Status URL

Sie können Folgendes nutzen:

Abfrage per API.
Benachrichtigungen an die Status URL.
Beides zusammen.

Bei Integrationen mit Benachrichtigungen an die Status URL hilft die Abfrage per API beim Abgleich, wenn sich eine Benachrichtigung verzögert oder Ihr Endpunkt vorübergehend nicht erreichbar ist.

Erstellen Sie keine doppelte Rechnung, nur weil eine Statusabfrage oder die Zustellung einer Benachrichtigung fehlschlägt.

Ablauf API + Hosted Checkout

Nutzen Sie dieses Modell, wenn Hosted Checkout selbst die Zahlungsseite für den Kunden bereitstellen soll, während Ihr Backend die API für Verfolgung und Abgleich nutzt.

Der Zahlungsablauf:

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

In diesem Modell übernimmt Hosted Checkout:

Die Zahlungsseite.
Die Auswahl der Zahlungsmethode.
Die Zahlungsanweisungen.
Die Kundenweiterleitungen.

Über die API können Sie den Zahlungsauftrag weiterhin anhand von orderId und sciName abrufen und den Status in Ihrem System abgleichen.

Statusverarbeitung mit Hosted Checkout

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

Kundenweiterleitungen sind Teil des Browserablaufs und erreichen Ihren Server nicht immer.

Aktualisieren Sie die Bestellung in Ihrem Backend anhand der Benachrichtigung an die Status URL und nutzen Sie bei Bedarf die Bestellabfrage per API zum Abgleich.

Empfohlenes Vorgehen:

Empfangen Sie die Hosted-Checkout-Benachrichtigung an der Status URL.
Prüfen Sie die Signatur der Benachrichtigung.
Aktualisieren Sie die Bestellung, wenn die Benachrichtigung gültig ist.
Nutzen Sie GET /api/orders als Fallback oder zum Abgleich.

Inhalt der Benachrichtigung und Regeln zur Signaturprüfung finden Sie unter Hosted-Checkout-Integration.

Fehlerbehandlung

Fehler der Merchant API liefern eine strukturierte Antwort mit einem oder mehreren Fehlern in data.errors.

Beispielstruktur:

{
  "status": "error",
  "data": {
    "errors": [
      {
        "errorMessage": "resourceNotFound",
        "errorType": "GENERAL",
        "errorId": "3f69d9b6",
        "errorDescription": "Resource not found",
        "errorField": null,
        "params": [],
        "requestParams": {}
      }
    ]
  }
}

Fehlerfelder:

Feld	Beschreibung
`errorMessage`	Maschinenlesbarer Fehlercode, den die API zurückgibt.
`errorType`	Fehlerkategorie.
`errorId`	Fehlerkennung, die Sie in Logs und Supportanfragen angeben können.
`errorDescription`	Für Menschen lesbare Fehlerbeschreibung.
`errorField`	Feld der Anfrage, auf das sich der Fehler bezieht, sofern verfügbar.
`params`	Zusätzliche Parameter zum Fehler, sofern verfügbar.
`requestParams`	Anfrageparameter zum Fehler, sofern verfügbar.

Häufige HTTP-Antworten:

HTTP-Status	Bedeutung
`400`	Die Anfrage ist fehlerhaft oder enthält ungültige Parameter.
`401`	Authentifizierungs-Header fehlen oder sind ungültig.
`404`	Die angeforderte Ressource wurde nicht gefunden.
`500`	Unerwarteter Serverfehler.

Die genauen Werte von errorMessage hängen vom Endpunkt und vom Fehler ab. Leiten Sie einen anwendungsseitigen Fehlercode nicht allein aus dem HTTP-Status ab.

Bei einem Fehler:

Protokollieren Sie errorId für Support und Diagnose.
Prüfen Sie errorField, sofern verfügbar.
Verwenden Sie in der programmatischen Fehlerbehandlung errorMessage statt errorDescription.
Erstellen Sie nach einer Anfrage mit unklarem Ergebnis nicht automatisch eine doppelte Rechnung.
Wiederholen Sie die Anfrage nur, wenn das gefahrlos möglich ist.

Tests und Sandbox

Volet.com bietet derzeit keine Sandbox und keine Staging-Umgebung für Integrationstests.

Wenn Sie Hosted Checkout nutzen, können Sie die Zahlungsseite für Kunden auf der Hosted-Checkout-Seite für Entwickler in einer Vorschau ansehen. Die Vorschau ist keine Sandbox und ersetzt keine Integrationstests.

Für eine Einführung in API, Hosted Checkout und Zahlungsablauf vor dem Livegang wenden Sie sich an das Vertriebsteam von Volet.com.

Test-Checkliste

Prüfen Sie den gesamten Ablauf Ihrer Integration, bevor Sie echte Krypto-Zahlungen annehmen.

Bei Integrationen nur mit API:

Rechnungsprüfung, falls verwendet.
Rechnungserstellung.
Korrekte Anzeige der Zahlungsadresse.
Anzeige von Destination-Tag oder Memo, falls erforderlich.
Korrekte Anzeige von Währung und Netzwerk.
Behandlung abgelaufener Rechnungen.
Speicherung von orderId und sciName.
Bestellabfrage über GET /api/orders.
Behandlung abgeschlossener Zahlungen.
Behandlung stornierter und erstatteter Zahlungen.
Behandlung doppelter orderId-Werte.
Behandlung von API-Fehlern.

Wenn Sie Benachrichtigungen an die Status URL nutzen:

Die Hosted-Checkout-Konfiguration enthält die richtige Status URL.
Derselbe Hosted-Checkout-Name wird als sciName übergeben.
Benachrichtigungen erreichen Ihr Backend.
Signaturen der Benachrichtigungen werden geprüft.
Doppelte Benachrichtigungen werden sicher verarbeitet.
Die Abfrage per API kann zum Abgleich genutzt werden.

Wenn Sie die Hosted-Checkout-Zahlungsseite nutzen, prüfen Sie zusätzlich:

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

Wichtige Hinweise

Bei Integrationen nur mit API müssen Kunden Hosted Checkout nicht aufrufen.
Die aktuelle Bestellabfrage erfordert sciName.
Eine Hosted-Checkout-Konfiguration kann allein für sciName und Benachrichtigungen an die Status URL genutzt werden, ohne die Hosted-Checkout-Seite anzuzeigen.
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 paymentStatus den Wert COMPLETED hat.
Berechnen Sie den Ablauf der Rechnung anhand von expirationDateMillis.
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.
Erstellen Sie nach einem Timeout mit unklarem Ergebnis oder einem vorübergehenden API-Fehler nicht automatisch eine weitere Rechnung.

Zahlungs-Gateway erstellen — API und Hosted Checkout erstellen und konfigurieren
Custodial-Krypto-Zahlungen akzeptieren — so funktionieren Custodial-Krypto-Zahlungen
Hosted-Checkout-Integration — die gehostete Zahlungsseite und Benachrichtigungen an die Status URL nutzen
Unterstützte Währungen und Tokens — unterstützte Währungen und Netzwerke
API-Referenz — vollständige Dokumentation der Methoden, Parameter und Antworten

Wann sich die API-Integration eignet​

Integrationsmodelle​

Bevor Sie beginnen​

Authentifizierung​

Zahlungsablauf nur mit API​

Schritt 1 (optional): Rechnungsdetails prüfen​

Schritt 2: Krypto-Rechnung erstellen​

Felder der Rechnungsanfrage​

GIVE und GET​

Währungscodes​

Felder der Rechnungsantwort​

Schritt 3: Zahlungsanweisungen anzeigen​

Schritt 4: Zahlungsstatus abfragen​

Zahlungsstatus​

Benachrichtigungen an die Status URL empfangen​

Benachrichtigungen an die Status URL einrichten​

Abfrage und Benachrichtigungen an die Status URL​

Ablauf API + Hosted Checkout​

Statusverarbeitung mit Hosted Checkout​

Fehlerbehandlung​

Tests und Sandbox​

Test-Checkliste​

Wichtige Hinweise​

Siehe auch​

Wann sich die API-Integration eignet

Integrationsmodelle

Bevor Sie beginnen

Authentifizierung

Zahlungsablauf nur mit API

Schritt 1 (optional): Rechnungsdetails prüfen

Schritt 2: Krypto-Rechnung erstellen

Felder der Rechnungsanfrage

`GIVE` und `GET`

Währungscodes

Felder der Rechnungsantwort

Schritt 3: Zahlungsanweisungen anzeigen

Schritt 4: Zahlungsstatus abfragen

Zahlungsstatus

Benachrichtigungen an die Status URL empfangen

Benachrichtigungen an die Status URL einrichten

Abfrage und Benachrichtigungen an die Status URL

Ablauf API + Hosted Checkout

Statusverarbeitung mit Hosted Checkout

Fehlerbehandlung

Tests und Sandbox

Test-Checkliste

Wichtige Hinweise

Siehe auch