Entwicklerdokumentation

Authentifizierung

Authentifizieren Sie jede Anfrage mit Ihrem geheimen Schlüssel im Authorization-Header. Erstellen Sie Schlüssel pro Shop unter Dashboard → API-Schlüssel (der vollständige Schlüssel wird einmalig angezeigt).

Rechnung erstellen

Senden Sie Bestellbetrag und Asset; die Chain ist optional. Sie erhalten eine gehostete checkoutUrl — leiten Sie Ihren Kunden dorthin. Ohne Chain wählt der Kunde das Netzwerk auf der Zahlungsseite.

Anfrage

curl -X POST https://nextcryptopay.com/api/v1/invoices \
  -H "Authorization: Bearer ncp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORDER-1001",
    "amount": 99.50,
    "currency": "USD",
    "chain": "tron",
    "asset": "USDT",
    "webhookUrl": "https://yourstore.com/webhooks/nextcryptopay",
    "redirectUrl": "https://yourstore.com/thank-you"
  }'

Antwort

{
  "id": "inv_abc123",
  "orderId": "ORDER-1001",
  "payAddress": "TJ9xH4n2k8sQw7Lm3vR5pZ1aB6cD8eF2g",
  "cryptoAmount": "99.50",
  "asset": "USDT",
  "chain": "tron",
  "status": "PENDING",
  "expiresAt": "2026-06-17T10:00:00.000Z",
  "checkoutUrl": "https://nextcryptopay.com/pay/inv_abc123"
}

redirectUrl ist das Ziel, wohin der Kunde wenige Sekunden nach der Zahlung geschickt wird. Ohne Angabe wird die Rücksprung-URL des Shops (Dashboard → Webhooks) verwendet. Setzen Sie eines von beiden — ohne beides bleibt der Kunde ohne Rückweg auf der Zahlungsseite. Liefern Sie niemals nur deshalb aus, weil jemand diese URL aufgerufen hat: Nur ein signaturgeprüfter invoice.paid-Webhook belegt die Zahlung.

Zahlungsstatus verfolgen

Fragen Sie die Rechnung ab oder abonnieren Sie Live-Updates über Server-Sent Events. Status: PENDING → CONFIRMING → PAID (oder EXPIRED / PARTIALLY_PAID).

# Poll the invoice
curl https://nextcryptopay.com/api/v1/invoices/inv_abc123

# Or subscribe to live updates (Server-Sent Events)
GET https://nextcryptopay.com/api/v1/invoices/inv_abc123/stream

Webhooks verifizieren

Bei jeder Statusänderung senden wir ein signiertes Ereignis per POST an Ihre Webhook-URL. Verifizieren Sie den x-nextcryptopay-signature-Header (HMAC-SHA256 des Roh-Bodys mit dem Webhook-Geheimnis Ihres Shops), bevor Sie ihm vertrauen. Antworten Sie innerhalb von 15 Sek. mit 2xx — andernfalls wiederholen wir mit Backoff. Die alten x-cryptopay-*-Header werden mit identischen Werten noch bis zum 31.03.2027 parallel gesendet; verwenden Sie in neuem Code die Namen x-nextcryptopay-*.

import crypto from "node:crypto";

// Legacy x-cryptopay-* headers carry identical values and are still sent in
// parallel until 2027-03-31 — prefer x-nextcryptopay-* in new code.
app.post("/webhooks/nextcryptopay", (req, res) => {
  const signature = req.headers["x-nextcryptopay-signature"];
  const timestamp = req.headers["x-nextcryptopay-timestamp"];

  // Reject stale deliveries (replay protection): within 5 minutes
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(401).end();
  }

  // Signature is HMAC of "timestamp.rawBody"
  const expected = crypto
    .createHmac("sha256", process.env.NEXTCRYPTOPAY_WEBHOOK_SECRET)
    .update(timestamp + "." + req.rawBody) // raw JSON body
    .digest("hex");

  if (
    signature.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  ) {
    return res.status(401).end();
  }

  // Dedupe by delivery id (same event may be retried)
  const deliveryId = req.headers["x-nextcryptopay-delivery"];
  if (alreadyProcessed(deliveryId)) return res.status(200).end();

  const { event, invoice } = req.body;
  if (event === "invoice.paid") fulfillOrder(invoice.orderId);

  res.status(200).end(); // reply 2xx within 15s, else we retry (6 attempts, backoff)
});

Unterstützte Chains

Tron (USDT/USDC · TRC20), Ethereum (USDT/USDC · ERC20), BSC (USDT · BEP20), TON (USDT · jetton), Bitcoin (BTC). Für jede erfolgreiche Zahlung fällt eine Plattformgebühr an, die pro Transaktion gedeckelt ist und von Ihrem vorab aufgeladenen USDT-Guthaben abgezogen wird (oder durch Ihr Tarifkontingent abgedeckt ist). Aktuelle Sätze finden Sie auf der Preisseite.