Coinbase-Commerce-kompatible API

Charge-Endpoints, der Header X-CC-Api-Key, das Charge-Objekt und mit X-CC-Webhook-Signature signierte Webhooks folgen der Dokumentation von Coinbase Commerce, sodass die offiziellen SDKs nach der Änderung einer einzigen Zeile funktionieren. Coinbase Commerce hat am 2026-03-31 aufgehört, Händler außerhalb der USA und Singapurs zu bedienen. 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.

Coinbase Commerce

Alle offiziellen SDKs nehmen eine Base-URL – ändern Sie eine Zeile (achten Sie auf den abschließenden /):

// Node(coinbase-commerce-node)
const { Client } = require("coinbase-commerce-node");
- Client.init(process.env.COINBASE_COMMERCE_API_KEY);
+ Client.init(process.env.COINBASE_COMMERCE_API_KEY, "https://blockwallets.io/coinbase/");

# Python(coinbase-commerce)
- client = Client(api_key=API_KEY)
+ client = Client(api_key=API_KEY, base_api_uri="https://blockwallets.io/coinbase/")

// PHP(coinbase/coinbase-commerce)
- ApiClient::init($apiKey);
+ ApiClient::init($apiKey, 'https://blockwallets.io/coinbase/');

curl -X POST https://blockwallets.io/coinbase/charges \
  -H "X-CC-Api-Key: $COINBASE_COMMERCE_API_KEY" -H "X-CC-Version: 2018-03-22" \
  -H "content-type: application/json" \
  -d '{"name":"Order #12345","description":"Pro plan","pricing_type":"fixed_price",
       "local_price":{"amount":"100.00","currency":"USD"},
       "redirect_url":"https://shop.example/success","cancel_url":"https://shop.example/cancel",
       "metadata":{"order_id":"12345"}}'
# → 201 {"data": {"id": "…", "code": "7C7V5ECK", "hosted_url": "https://blockwallets.io/pay/inv_…", "timeline": [{"status": "NEW", …}], …}}

Unterstützte Endpoints

Nicht verfügbar: /charges/:code/resolve (400 – behandeln Sie unterzahlte Charges im Dashboard), /checkouts, /events, /invoices (404).

Webhooks

Coinbase-Webhooks gelten kontoweit, unsere ebenfalls: Sie gehen an die im Dashboard gesetzte Callback-URL (mit Test-Zugangsdaten erstellte Charges gehen an die Test-Callback-URL). Der Body ist der von Coinbase {id, scheduled_for, attempt_number, event: {id, type, api_version, created_at, data}} mit der vollständigen Charge in data; X-CC-Webhook-Signature = HMAC-SHA256(shared secret, Rohtext), sodass Webhook.verifyEventBody der SDKs unverändert funktioniert. Bei Wiederholungen bleibt event.id gleich und attempt_number steigt – deduplizieren Sie über event.id.

import crypto from "node:crypto";

// Same as the SDK's Webhook.verifySigHeader: HMAC-SHA256(shared secret, raw body)
function verifyWebhook(rawBody, sig, sharedSecret) {
  const hmac = crypto.createHmac("sha256", sharedSecret).update(rawBody, "utf8").digest("hex");
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(sig || ""));
}
// verifyWebhook(rawBody, req.headers["x-cc-webhook-signature"], process.env.COINBASE_WEBHOOK_SECRET)
// or with the official SDK:Webhook.verifyEventBody(rawBody, signature, sharedSecret)

Bei Abfragen sehen Sie außerdem NEW (wartet auf Zahlung) und PENDING (Zahlung on-chain gesehen, wird bestätigt). Liefern Sie bei charge:confirmed aus: charge:created, charge:pending, charge:delayed und charge:resolved senden wir nicht.

Unterschiede zu Coinbase Commerce

• pricing_type muss fixed_price sein; local_price.currency muss USD sein (USDC / USDT zu 1:1). no_price und andere Fiat-Währungen liefern 400.
• Die Adresse erscheint, sobald der Kunde im Checkout Coin und Netzwerk wählt: addresses enthält nur dieses Netzwerk, pricing nur local sowie nach der Wahl settlement; keine exchange_rates, kein checkout und keine Branding-Felder.
• metadata wird unverändert gespeichert und zurückgegeben (bis 4 KB).
• Erstattungen erscheinen nicht in der Timeline; sehen Sie sie im Dashboard.

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.