NOWPayments-kompatible API

Pfade, der Header x-api-key, Request- und Response-Felder, Status und die IPN-Signatur x-nowpayments-sig folgen der Dokumentation von NOWPayments, sodass vorhandener Code meist nur eine neue Base-URL, einen neuen API key und ein neues IPN secret braucht. Sie kommen von woanders? Siehe die Migrationsübersicht.

Darunter liegt eine ganz normale blockwallets-Rechnung: Die Empfangsadressen gehören Ihnen, die Zahlungsseite ist unser gehosteter Checkout, und eine Zahlung zählt erst, wenn sie on-chain bestätigt und gegen einen zweiten Node geprüft wurde. Unten: drei Schritte, dann was jede API unterstützt und wie sie sich vom Original unterscheidet – Parameter, die wir nicht umsetzen, liefern einen Fehler, statt stillschweigend ignoriert zu werden.

Drei Schritte

1. Besorgen Sie sich ein Händlerkonto (auf der Startseite beantragen) und tragen Sie im Dashboard unter „Entwickler › Integration & Keys“ bei „Website-Domains“ Ihre Domains ein. Callback-URLs (ipn_callback_url) und Weiterleitungs-URLs (success_url / cancel_url / redirect_url) müssen auf diesen Domains oder der Domain Ihrer Callback-URL liegen – ein geleakter Schlüssel kann Webhooks so nicht woandershin lenken.
2. Erzeugen Sie kompatible Zugangsdaten im Händler-Dashboard unter „Entwickler › Integration & Keys“, je einen Satz für Live und für Test: NOWPayments erhält einen API key + IPN secret, Coinbase Commerce einen API key + Webhook shared secret. Sie werden nur einmal angezeigt; wir speichern nur Hashes / Chiffretext.
3. Richten Sie Ihren Code auf die untenstehende Base-URL und nutzen Sie die neuen Schlüssel. Testen Sie zuerst mit den Test-Zugangsdaten auf Testnets und wechseln Sie dann auf Live.

NOWPayments

- const NP = "https://api.nowpayments.io/v1";
+ const NP = "https://blockwallets.io/nowpayments/v1";

const res = await fetch(`${NP}/payment`, {
  method: "POST",
  headers: { "x-api-key": process.env.NOWPAYMENTS_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({
    price_amount: 49.9, price_currency: "usd", pay_currency: "usdttrc20",
    order_id: "A-1001", order_description: "Pro plan",
    ipn_callback_url: "https://shop.example/ipn/nowpayments",
  }),
});
const { payment_id, pay_address, pay_amount } = await res.json();

Unterstützte Endpoints

Nicht verfügbar: Payouts, Conversions, Custody-Sub-Partner, Abonnements, update-merchant-estimate, Fiat-Zahlungen. Diese Pfade liefern 404.

IPN-Callbacks

Erreicht eine Zahlung einen Endstatus, senden wir ein POST an die beim Erstellen angegebene ipn_callback_url, mit x-nowpayments-sig = HMAC-SHA512(IPN secret, das rekursiv nach Schlüsseln sortierte JSON) – exakt der Prüfcode von NOWPayments. Der gesendete Body ist bereits sortiertes, kompaktes JSON, ein HMAC über den Rohtext funktioniert also ebenfalls (und ist in PHP / Python die sicherste Wahl, da deren erneutes Kodieren sehr kleiner Dezimalzahlen von JS abweichen kann). Fehlgeschlagene Callbacks werden nach 1 Min., 5 Min., 30 Min., … wiederholt – insgesamt 8 Versuche.

import crypto from "node:crypto";

// Same as the NOWPayments docs (our body is already sorted, so hashing the raw body works too)
function sortObject(obj) {
  return Object.keys(obj).sort().reduce((r, k) => {
    r[k] = obj[k] && typeof obj[k] === "object" ? sortObject(obj[k]) : obj[k];
    return r;
  }, {});
}
function verifyIpn(params, sig, ipnSecret) {
  const hmac = crypto.createHmac("sha512", ipnSecret).update(JSON.stringify(sortObject(params))).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(sig || ""));
}
// verifyIpn(req.body, req.headers["x-nowpayments-sig"], process.env.NOWPAYMENTS_IPN_SECRET)

$raw = file_get_contents('php://input');
$data = json_decode($raw, true);
tksort($data);  // the recursive ksort from the NOWPayments docs
$hmac = hash_hmac('sha512', json_encode($data, JSON_UNESCAPED_SLASHES), trim($ipnSecret));
$ok = hash_equals($hmac, $_SERVER['HTTP_X_NOWPAYMENTS_SIG'] ?? '');

confirmed, sending und failed erscheinen nie: Nach der Bestätigung ist es finished und wird Ihrem Guthaben gutgeschrieben; nichts wird weitergeleitet.

Währungskürzel

Unterschiede zu NOWPayments

• price_currency ist nur usd (plus usdt / usdc zu 1:1); andere Fiat-Währungen liefern 400.
• pay_amount (ein fester Krypto-Betrag), payout_address / payout_currency / payout_extra_id und customer_email werden nicht unterstützt und liefern 400.
• is_fixed_rate wird akzeptiert, hat aber keine Wirkung: Wir fixieren den Kurs immer (BTC / LTC usw. zum Median mehrerer Börsen, für 30 Minuten). Bei is_fee_paid_by_user true wird die Plattformgebühr zu pay_amount addiert (die Plattformgebühr beträgt 1%, bei höherem Volumen weniger; siehe Preise).
• Zahlungen sind bis zu 12 Stunden gültig (NOWPayments: 7 Tage). partially_paid_url wird gespeichert und zurückgegeben, aber der Checkout leitet nicht dorthin weiter.
• payment_id ist eine 10-stellige Zahl; bei mit /invoice erstellten Rechnungen entspricht die payment_id der Zahlung der id der Rechnung, und eine Rechnung hat genau eine Zahlung (keine erneuten Einzahlungen per parent_payment_id).
• Gesendet werden nur IPNs für Endstatus und partially_paid (Tabelle oben), keine für waiting / confirming; fee.serviceFee ist die Plattformgebühr (der erhaltene Betrag × der Satz bei Erstellung der Rechnung, Standard 1%), andere Gebühren sind 0.

Testmodus

Mit Test-Zugangsdaten erstellte Charges und Zahlungen laufen im Testnet der jeweiligen Chain, und ihre Webhooks werden mit dem Test-IPN-secret / shared secret signiert – völlig getrennt von Live: Ein Test-Schlüssel sieht keine Live-Zahlungen.

Alles Übrige (Checkout, Bestätigungen, Netzwerke und Mindestbeträge, Erstattungen) funktioniert wie in der Hauptdokumentation.