Developers

Orders und Idempotenz

Das Erstellen einer Order sperrt den Kurs und weist eine Einzahlungsadresse zu. Es ist die eine Stelle, an der ein Integrationsfehler Geld bewegt: Idempotenz ist dort keine Bequemlichkeit.

Veröffentlichter Vertrag, noch nicht offen

Diese Endpunkte sind heute nicht freigeschaltet. Sie sind dokumentiert, damit Sie Ihre Integration im Voraus aufbauen können; ihre Form ist festgelegt, und jede bahnbrechende Änderung wird über eine neue Version und einen Changelog-Eintrag laufen.

POST/api/v1/ordersPublished contract, not open

Auftrag erstellen

Sperrt den Kurs und gibt eine dedizierte Einzahlungsadresse zurück. Der Auftrag trägt die Aufschlüsselung als gesperrt: Er ist wiederholbar, sodass Sie den exakt angewendeten Preis auch Monate später rekonstruieren können. Der Idempotency-Key-Header ist erforderlich.

Authentifizierung: Authorization: Bearer … Siehe Authentifizierung

Parameter

Parameter
Feld	Typ	Beschreibung
`quoteId`erforderlich	string	Kennung des akzeptierten Angebots.
`beneficiary`erforderlich	object	Felder, die durch das Zahlungsweg-Schema vorgegeben sind. Der Name muss mit der verifizierten Identität übereinstimmen: keine Auszahlungen an Dritte.
`networkId`erforderlich	string	Netzwerk, über das die Einzahlung gesendet wird. Es bestimmt die zurückgegebene Adresse und in einigen Netzwerken das Pflicht-Memo.

Anfragebash

curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'

Antwort – veröffentlichter Vertragjson

{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}

Das Memo ist auf den meisten Netzwerken null und auf XRP, Stellar und TON Pflicht. Wenn es dort weggelassen wird, gehen die Gelder verloren: Behandeln Sie das Feld als erforderlich, sobald es nicht null ist.

Mögliche Fehler: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. Vollständiger Katalog

GET/api/v1/orders/{reference}Published contract, not open

Auftrag lesen

Aktueller Zustand und Verlauf der Übergänge mit Zeitstempel. Der Verlauf ist die Quelle der Wahrheit: Er ist append-only, wird nie überschrieben, und er beantwortet die Frage „Warum hat sich mein Auftrag zu diesem Zeitpunkt in diesen Zustand bewegt?“.

Authentifizierung: Authorization: Bearer … Siehe Authentifizierung

Anfragebash

curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'

Antwort – veröffentlichter Vertragjson

{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

Mögliche Fehler: unauthorized, not_found. Vollständiger Katalog

Idempotenz

Eine Erstellungsanfrage, die im Netzwerk ausläuft, sagt Ihnen nicht, ob die Order erstellt wurde. Ohne Idempotenzschlüssel haben Sie nur zwei schlechte Optionen: Wiederholen und riskieren zwei Orders, oder nicht wiederholen und riskieren keine.

Headerhttp

Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

Ein Schlüssel pro Absicht

Der Schlüssel identifiziert die Absicht „diese Order erstellen“, nicht die HTTP-Anfrage. Eine eindeutige ID auf Ihrer Seite: eine Warenkorb-ID, eine UUID, die vor dem Aufruf generiert wird, niemals ein Zähler.

Eine Wiederholung gibt die ursprüngliche Antwort zurück

Die Wiederholung desselben Schlüssels mit demselben Body gibt die Antwort der ersten Anfrage mit demselben HTTP-Status zurück. Das macht eine Wiederholung sicher, auch nach einem Timeout.

Gleicher Schlüssel, anderer Body: Konflikt

Die Antwort ist ein expliziter Konflikt. Wenn sich der Inhalt ändert, muss sich der Schlüssel ändern: Sonst kann niemand sagen, welche der beiden Orders wiederholt werden soll.

24-Stunden-Aufbewahrung

Danach wird der Schlüssel vergessen und eine Wiederholung würde eine neue Order erstellen. Wiederholen Sie innerhalb des Fensters oder prüfen Sie den Zustand mit dem Lese-Endpunkt.

Der Memo, bei Netzwerken, die eines benötigen

Bei XRP, Stellar und TON reicht die Einzahlungsadresse nicht aus: Eine zusätzliche Kennung bezeichnet den endgültigen Empfänger. Es ist die teuerste Ursache für Vorfälle in einer Off-Ramp-Integration.

Eine Einzahlung ohne Memo ist eine verlorene Einzahlung

Das Memo-Feld ist bei den meisten Netzwerken null und bei solchen, die es benötigen, nicht null. Behandeln Sie es als obligatorisch, sobald es nicht null ist, und zeigen Sie es mit demselben Gewicht wie die Adresse an. Eine Einzahlung ohne Memo auf einer gemeinsamen Adresse erfordert manuelle Wiederherstellung, die nicht immer gelingt.

Order-Zustände

Die folgenden Zustände sind die, die Ihre Integration beobachten kann. Übergänge werden mit Zeitstempel versehen und angehängt, nie überschrieben: Die Historie beantwortet „Warum hat sich meine Order zu diesem Zeitpunkt in diesen Zustand bewegt?“.

Order-Zustände
Zustand	Bedeutung
`QUOTE_LOCKED`	Der Kurs ist eingefroren. Die Order wartet auf Empfängerdaten oder Identitätsprüfung.
`AWAITING_DEPOSIT`	Die Einzahlungsadresse ist zugewiesen und das Einzahlungsfenster läuft. Das ist der einzige Moment, um Gelder zu senden.
`DEPOSIT_DETECTED`	Eine eingehende Transaktion wird im Netzwerk gesehen, noch nicht bestätigt. Beruhigen Sie den Benutzer, liefern Sie nichts.
`CONFIRMING`	Bestätigungen sammeln sich an. Die erforderliche Anzahl hängt vom Netzwerk ab, nicht vom Betrag.
`DEPOSIT_CONFIRMED`	Die Einzahlung ist gesichert. Ab hier werden Compliance- und Neubepreisungsregeln bewertet.
`UNDERPAID`	Der erhaltene Betrag liegt unter dem erwarteten Wert außerhalb der Toleranz. Drei Ergebnisse: aufstocken, mit dem erhaltenen Betrag fortfahren oder erstattet werden.
`OVERPAID`	Der erhaltene Betrag übersteigt die Erwartung. Der ursprüngliche Betrag bleibt zum festgelegten Kurs, der Überschuss wird separat behandelt.
`PAYOUT_QUEUED`	Die Überweisung ist in der Warteschlange. Die Warteschlange garantiert, dass eine Auszahlung genau einmal gesendet wird, auch wenn mehrere Worker parallel ausgelöst werden.
`PAYOUT_SENT`	Die Überweisung hat den Zahlungsweg verlassen. Gesendet bedeutet nicht empfangen: Die endgültige Verzögerung hängt von der Bank des Empfängers ab.
`COMPLETED`	Die Abrechnung ist vom Zahlungsweg bestätigt. Endzustand.
`PAYOUT_FAILED`	Der Zahlungsweg hat die Überweisung abgelehnt oder zurückgesendet. Kein automatischer erneuter Versuch: Die Ursache liegt fast immer im Detail.
`REFUNDED`	Gelder wurden an die Ursprungsadresse zurückgegeben, abzüglich Netzwerkgebühren. Endzustand.