Crypto Payment Gateway API: Vollständiger Integrationsleitfaden für 2026

Eine Crypto Payment Gateway API ist die programmatische Schnittstelle, die es Ihrer Anwendung ermöglicht, Zahlungsanfragen zu erstellen, On-Chain-Transaktionsbestätigungen zu überwachen und Abrechnungen durchzuführen — ohne Wallets oder private Schlüssel direkt verwalten zu müssen. Sie rufen einen REST-Endpoint auf, das Gateway übernimmt die Blockchain-Schicht, und Ihr Backend erhält einen Webhook, wenn die Zahlung eingeht.

Das unterscheidet sich von einem Zahlungsabwickler (der Fiat-Autorisierungen verarbeitet) oder einer Self-Custody-Wallet (bei der Nutzer Transaktionen selbst signieren). Die API steht dazwischen: Ihre App steuert die User Experience, das Gateway verarbeitet Bestätigungen, Compliance-Prüfungen und optionale Fiat-Konvertierung.

Im Zahlungszyklus übernimmt das Crypto Payment Gateway vier Aufgaben: Generierung einer Einzahlungsadresse oder Zahlungs-URL, Blockchain-Überwachung auf eingehende Gelder, Webhook-Auslösung bei Erreichen des Bestätigungsschwellwerts und optionale Konvertierung des empfangenen Betrags. Ihre Integration muss nur die Schritte 1 und 3 verarbeiten.

Der vollständige Zahlungsablauf besteht aus fünf Schritten.

Schritt 1 — Zahlungsabsicht erstellen

Ihr Server ruft POST /payments mit dem erwarteten Betrag, der Währung und einer von Ihnen generierten orderId auf. Das Gateway gibt paymentId, eine Einzahlungsadresse und einen Ablaufzeitstempel zurück.

Schritt 2 — Weiterleitung oder Anzeige

Bei Hosted Checkouts leiten Sie den Nutzer zur Gateway-URL weiter. Bei direkten Integrationen zeigen Sie die Einzahlungsadresse und den QR-Code in Ihrer eigenen UI an.

Schritt 3 — Webhook-Callback empfangen

Wenn das Gateway eine eingehende Transaktion erkennt, sendet es eine POST-Anfrage an Ihre Webhook-URL. Der Payload enthält paymentId, aktuellen Status, Anzahl der Bestätigungen und den empfangenen Betrag.

Schritt 4 — Verifizieren und Bestätigen

Prüfen Sie vor jeder Aktion die HMAC-Signatur in den Anfrage-Headern. Falls sie nicht übereinstimmt, lehnen Sie die Anfrage ab. Rufen Sie dann GET /payments/{id} auf, um den kanonischen Status serverseitig zu prüfen.

Schritt 5 — Bestellung ausführen

Sobald der serverseitige Status als completed bestätigt ist, führen Sie die Bestellung idempotent aus und verwenden Sie paymentId als Idempotenz-Schlüssel.

Die Konfiguration des Crypto Payment Gateways bestimmt den synchronen oder asynchronen Abrechnungsweg.

Eine gut konzipierte Payment Gateway API bietet vier Gruppen von Kern-Endpoints.

Zahlungsabsicht erstellen — POST /payments

Eine minimale Anfrage sieht so aus:

{
  "orderId": "ord_abc123",
  "amount": "250.00",
  "currency": "USD",
  "payCurrency": "ETH",
  "callbackUrl": "https://yourapp.com/webhooks/payments",
  "successUrl": "https://yourapp.com/orders/ord_abc123/success",
  "expiresIn": 1800
}

Die Antwort enthält paymentId, depositAddress, expectedAmount in Krypto und expiresAt.

Transaktionsstatus — GET /payments/{id}

Verwenden Sie diesen Endpoint zur Statusbestätigung nach Erhalt eines Webhooks.

Rückerstattungen — POST /refunds

Übergeben Sie paymentId und amount. Das Gateway initiiert eine On-Chain-Überweisung zurück an die Absenderadresse.

Abrechnungsberichte — GET /settlements

Fragen Sie Abrechnungen nach Datumsbereich für die Abstimmung ab.

Webhooks sind besser als Polling, weil Sie sofort über Bestätigungen informiert werden.

Warum Webhooks besser als Polling sind

Polling erzeugt unnötige API-Aufrufe und erhöht die Latenz. Webhooks senden Ereignisse, sobald Bestätigungsschwellwerte erreicht werden.

HMAC-SHA256-Signaturverifizierung

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

  const expected = Buffer.from(expectedSig, 'hex');
  const received = Buffer.from(signature, 'hex');

  if (expected.length !== received.length) return false;
  return crypto.timingSafeEqual(expected, received);
}

app.post('/webhooks/payments', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-signature'];
  if (!verifyWebhookSignature(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  res.json({ received: true });
});

Übergeben Sie den rohen Request-Body (Buffer), nicht den geparsten JSON.

Wiederholung mit exponentiellem Backoff

Gateways wiederholen fehlgeschlagene Webhooks — typischerweise 3-5 Mal mit exponentiellem Backoff.

Idempotenz-Schlüssel

Verwenden Sie paymentId als Idempotenz-Schlüssel zur Vermeidung doppelter Bestellungen.

Die meisten großen Gateways liefern SDKs für TypeScript/Node, Python, Go und PHP.

SDK verwenden wenn:

• •Ihr Stack einer unterstützten Sprache entspricht
• •Sie Typsicherheit für Request/Response-Objekte benötigen
• •Sie eingebaute Retry-Logik möchten

Raw REST verwenden wenn:

• •Ihr Stack nicht unterstützt wird (Rust, Elixir)
• •Sie präzise Kontrolle über HTTP-Verhalten benötigen
• •Die SDK-Version hinter der API-Version zurückliegt

Für die meisten Teams ist das SDK die richtige Wahl. Erfahren Sie mehr darüber, was Blockchain APIs für Entwickler unter der Haube tun.

Eine realistische Integrationsanleitung in fünf Schritten.

Schritt 1: Einen Payment-Gateway-API-Anbieter wählen

Bewerten Sie fünf Kriterien: unterstützte Blockchains, Gebührenstruktur, Sandbox-Qualität, Dokumentationstiefe und Compliance-Bereitschaft.

Für Unternehmen mit DeFi-Anforderungen prüfen Sie auch die Kompatibilität mit DeFi-Plattformen.

Schritt 2: API-Schlüssel und Sandbox-Zugang erhalten

Ihr API-Schlüssel-Set besteht aus einem öffentlichen Schlüssel (in Request-Headern) und einem geheimen Schlüssel (für HMAC-Signierung). Speichern Sie beide in Umgebungsvariablen.

Schritt 3: Erste Zahlungsabsicht erstellen

const axios = require('axios');

async function createPayment(orderId, amountUSD) {
  const response = await axios.post(
    'https://api.yourgateway.com/v1/payments',
    {
      orderId,
      amount: amountUSD.toString(),
      currency: 'USD',
      payCurrency: 'USDT_ETH',
      callbackUrl: process.env.WEBHOOK_URL,
      expiresIn: 3600,
    },
    {
      headers: {
        Authorization: `Bearer ${process.env.GATEWAY_API_KEY}`,
        'Idempotency-Key': orderId,
        'Content-Type': 'application/json',
      },
    }
  );

  return response.data;
}

Schritt 4: Webhook-Callbacks verarbeiten

Richten Sie Ihren Webhook-Endpoint vor dem Testen ein. In der Sandbox erlauben die meisten Gateways das manuelle Auslösen von Webhook-Ereignissen.

Schritt 5: Bestellung verifizieren und ausführen

Nach Erhalt eines completed-Webhooks immer eine serverseitige Verifizierung (GET /payments/{id}) durchführen, dann die Bestellung idempotent ausführen.

Sicherheit ist kein Nachgedanke nach dem Launch. Diese Anforderungen gehören in die Architekturentscheidungsphase.

Transportsicherheit

Mindestens TLS 1.3 für die gesamte API-Kommunikation.

API-Schlüsselverwaltung

Rotieren Sie API-Schlüssel vierteljährlich. Verwenden Sie separate Schlüsselpaare für Sandbox und Produktion.

KYC/AML-Compliance

Für Unternehmen, die über bestimmten Schwellenwerten abwickeln, gelten die FATF-AML-Leitlinien. PCI-DSS-Standards gelten technisch für Krypto-Zahlungsflüsse.

Signierte Anfragen

Einige Anbieter erfordern signierte API-Anfragen (ähnlich AWS Signature V4). Für Unternehmen, die vollständige Fintech-Lösungen entwickeln, ist ein API-Sicherheitsarchitektur-Review vor dem Launch unerlässlich.

So vergleichen sich die wichtigsten Anbieter in den Dimensionen, die für Integrationsentscheidungen wirklich wichtig sind.

Das sind die Fehler, die Teams in der Produktion machen, nicht in Tutorials.

Falsche Bestätigungsschwellen

Bitcoin benötigt 6 Bestätigungen für hochwertige Transaktionen — etwa 60 Minuten. 1 Bestätigung zu verwenden öffnet Double-Spend-Angriffe. Setzen Sie Schwellen nach Transaktionswert: 1 für <$100, 3 für $100-$1000, 6 für >$1000 auf Bitcoin Mainnet.

On-Chain-Timeout-Behandlung

Krypto-Transaktionen können bei niedrigen Gas-Gebühren stundenlang unbestätigt bleiben. Halten Sie den watchAddress-Status 24-72 Stunden nach Ablauf der Zahlungsabsicht aktiv.

Gas-Schätzungsfehler

Fügen Sie bei ETH-denominierten Zahlungen einen 5-10% Toleranzpuffer hinzu oder wechseln Sie zu USDT/USDC-Stablecoins.

Erfahren Sie mehr zu den Entwicklungskosten im Artikel über Crypto-Payment-Gateway-Entwicklung.