Einführung/Allgemeine Informationen

Allgemeine Informationen

Technische Spezifikation für die Integration der Kryptowährungs-Zahlungsabwicklung und -Auszahlungen mit 2328.io.

Willkommen zur Dokumentation der 2328.io API. Diese Referenz beschreibt, wie Sie die Verarbeitung von Kryptowährungszahlungen und Auszahlungen in Ihre Anwendung integrieren.

Erste Schritte

So starten Sie mit der Integration:

Erstellen Sie ein Händlerkonto und ein Projekt auf 2328.io
Beziehen Sie Ihre Projekt-UUID und Ihren API-Schlüssel aus den Projekteinstellungen
Erzeugen Sie einen separaten Payout-API-Schlüssel, falls Sie Auszahlungen nutzen möchten
Lesen Sie den Abschnitt Authentifizierung, um zu erfahren, wie Anfragen signiert werden
Führen Sie Ihren ersten Aufruf Zahlung erstellen aus

Basis-URL

Alle Produktiv-API-Anfragen verwenden die folgende Basis-URL:

Text

https://api.2328.io/api

Alle Anfragen müssen über HTTPS erfolgen. Anfragen ohne HTTPS werden blockiert.

Was Sie tun können

Mit der 2328.io API können Sie:

Krypto-Zahlungen akzeptieren — Zahlungssitzungen erstellen und Kunden zu einem gehosteten Checkout oder einer Telegram MiniApp weiterleiten
Mittel auszahlen — programmatisch Auszahlungen von Ihrem Händlerguthaben an eine beliebige Blockchain-Adresse senden
Guthaben prüfen — sehen Sie die Händlerguthaben pro Währung, USD-Äquivalente und durch AML gesperrte Beträge
Statische Wallets verwenden — permanente Einzahlungsadressen erzeugen, die an einen Benutzer oder eine Bestellung gebunden sind
Wechselkurse abrufen — Kurse in Echtzeit für Fiat- und Krypto-Paare ermitteln
Webhooks empfangen — sofort benachrichtigt werden, wenn sich der Status einer Zahlung ändert

Ratenbegrenzung

Die API erlaubt bis zu 10 Anfragen pro Sekunde pro Projekt. Anfragen, die das Limit überschreiten, erhalten eine HTTP-429 Too Many Requests-Antwort — warten Sie ab und versuchen Sie es erneut.

Wählen Sie das richtige Integrationsmuster

Anforderung	Empfohlenes Muster	Warum
Lassen Sie den Kunden wählen, wie er bezahlen möchte	Hosted checkout	Erstellen Sie eine Zahlung und leiten Sie weiter zu `result.url`; 2328.io zeigt derzeit verfügbare Richtungen an.
Halten Sie den Kunden in Ihrem eigenen Checkout	Direktadresse H2H invoice	Senden Sie `to_currency` und `network` beim Erstellen der Zahlung; geben Sie die zurückgegebenen `address`, `payer_amount` und `qr` aus.
Belasten Sie genau `25 USDT` oder `0.001 BTC`	In Kryptowährung nominierte invoice	Legen Sie die Kryptowährung in `currency` und den genauen Dezimalbetrag in `amount` ab.
Geben Sie jedem Benutzer eine wiederverwendbare Einzahlungsadresse	Static wallet	Die Adresse ist permanent und kann viele unabhängige Einzahlungen empfangen.
Normalisieren Sie eingehende Vermögenswerte in eine Bilanzwährung	Auto-convert	Konfigurieren Sie Projektregeln im Dashboard und verwenden Sie das `convert`-Ergebnis, wenn die Konvertierung abgeschlossen ist.
Tauschen Sie ein bestehendes merchant-Guthaben	Manual convert	Vorschau mit `/v1/convert/price`, dann ausführen mit `/v1/convert`.
Senden Sie Gelder an eine Blockchain-Adresse	Auszahlung	Verwenden Sie den separaten Payout-API-Schlüssel, berechnen Sie zuerst und gleichen Sie anschließend den Auszahlungsstatus ab.

Hosted checkout und H2H sind zwei Darstellungen derselben Payment-API. H2H erstellt keine schwächere oder unsignierte Zahlung: Das backend erstellt weiterhin das invoice, 2328.io besitzt weiterhin die Adresse und den Status und signierte webhooks bleiben für settlement autoritativ.

Integrationsinvarianten

Diese Regeln gelten für jede production-Integration:

Nur Backend — halten Sie API-Schlüssel aus Browsern, mobilen Anwendungen, Protokollen, Analysen und Support-Screenshots heraus.
Dezimalstrings — senden und speichern Sie Geld als Strings. Runden Sie niemals Kryptowährungen oder Wechselkurse mit binärer Fließkommaarithmetik.
Unveränderliche idempotency-Schlüssel — erzeugen Sie order_id vor der ersten Anfrage und speichern Sie die vollständige Anfrage damit. Ein retry mit demselben order_id kann das ursprüngliche Objekt zurückgeben, anstatt geänderte Felder anzuwenden.
Webhook-zuerst settlement — Weiterleitungen, Client-Polling, von Benutzern bereitgestellte Transaktions-Hashes und HTTP-Timeouts sind kein Zahlungsnachweis.
Überprüfen, duplizieren, dann ändern — überprüfen Sie das HMAC, beanspruchen Sie einen idempotency-Datensatz atomar, aktualisieren Sie die Bestellung/den Saldo einmal und geben Sie schnell HTTP 200 zurück.
Reconciliation — fragen Sie regelmäßig den Zahlungs-, Static-Wallet- und Auszahlungsstatus ab, damit ein verlorenes webhook keinen dauerhaften Konflikt hinterlassen kann.
Dynamische Verfügbarkeit — validieren Sie Währungs-/Netzwerk-Paare mit /v1/directions; ein unterstützter Vermögenswert kann trotzdem vorübergehend in einer Einzahlungs- oder Auszahlung Richtung deaktiviert sein.
Explizite Statusrichtlinie — entscheiden Sie, wie Ihr Produkt Teilzahlungen, Überzahlungen, Ablauf, AML-Sperre, Conversion fallback und mehrdeutige Upstream-Timeouts behandelt, bevor es live geht.

Empfohlene zu speichernde Daten

Für Zahlungen speichern Sie mindestens uuid, order_id, den ursprünglichen Anforderungstext, amount, currency, payer_currency, payer_amount, network, address, expires_at, den neuesten payment_status, txid, payment_amount, merchant_amount, den optionalen convert-Block und die verifizierten Rohdaten webhook payload.

Für static wallets halten Sie die Wallet uuid, Adresse, Währung, Netzwerk, Kunden-/Kontoreferenz, Status und Callback-URL getrennt von Einzahlungsaufzeichnungen. Jede Einzahlung benötigt ihre eigene Transaktion uuid, txid, Status, erhaltenen Betrag, merchant Betrag und Konversionsergebnis.