Cryptomus-kompatible API

Mit blockwallets nehmen Sie USDT und USDC an, dazu BTC, LTC, DOGE, BCH und native Coins (gutgeschrieben in US-Dollar zu einem fixierten Kurs): Der Kunde zahlt, wir bestätigen es on-chain, dann benachrichtigen wir Sie. API, Signaturen und Webhooks sind dieselben wie bei Cryptomus – wenn Sie Cryptomus schon integriert haben, ändern Sie die Domain und sind fertig. Zuerst die Funktionsweise, dann die API.

Zwei Wege zum Geld

Beide nehmen jeden Betrag an: Bestellungen zum Festpreis und Aufladungen, bei denen der Kunde den Betrag selbst eingibt. Nach der Zahlung versenden Sie die Ware oder schreiben dem Kunden Guthaben gut. Der einzige Unterschied ist, ob jede Zahlung eine neue Adresse bekommt.

Im Zweifel nehmen Sie Rechnungen. Ohne Code sind die Zahlungslinks im Dashboard Rechnungen, die für Sie erstellt werden. Noch kein Händler? Beantragen Sie den Zugang auf der Startseite; nach der Freigabe melden Sie sich im Händler-Dashboard an und probieren auf der Startseite des Dashboards zuerst „Zahlung ausprobieren“ mit einem kleinen Betrag aus (das Geld geht auf Ihr eigenes Guthaben).

Wie eine Rechnung abläuft

An einer Zahlung wirken vier Parteien mit: der Kunde, Ihre Website, blockwallets und die Blockchain. Das Diagramm läuft zeitlich von oben nach unten; die rechte Spalte ist der Status der Rechnung in jedem Schritt.

Kurz in fünf Schritten:

1. Sie erstellen eine Rechnung (ein Zahlungslink erledigt das für Sie, oder Ihr Server ruft /v1/payment auf), erhalten die url der Zahlungsseite und leiten den Kunden dorthin weiter.
2. Auf der Zahlungsseite wählt der Kunde Coin und Netzwerk, erhält eine eigene Adresse samt Betrag und zahlt aus einer Wallet oder von einer Börse.
3. Wir sehen die Überweisung on-chain, warten auf genug Bestätigungen und prüfen sie dann gegen einen zweiten Node-Anbieter (damit ein Node sie nicht fälschen kann).
4. Die Rechnung wird paid, und wir senden sofort einen signierten Webhook per POST an Ihre url_callback; wenige Sekunden später schickt die Zahlungsseite den Kunden zurück zu Ihrer url_success.
5. Das Geld wird Ihrem Guthaben gutgeschrieben; zahlen Sie es im Händler-Dashboard auf Ihre eigene Wallet aus.

Rechnungsstatus

Wenn is_final true ist, ändert sich der Status nicht mehr (außer bei verspäteten Zahlungen).

Zahlungslinks (ohne Code)

Händler-Dashboard → „Zahlungen › Zahlungslinks“ → Beschreibung und Betrag eingeben (ein Netzwerk festlegen oder den Kunden wählen lassen) → erstellen. Jeder Link hat eine URL und einen QR-Code.

• Jedes Mal, wenn jemand den Link öffnet, wird eine neue Rechnung erstellt, ein Link ist also wiederverwendbar (z. B. „Mitgliedschaft $99“).
• Jede Zahlung erscheint unter „Zahlungen › Zahlungseingänge“; zahlen Sie sie unter „Finanzen › Guthaben & Auszahlung“ auf Ihre Wallet aus.
• Wenn Sie unter „Entwickler › Integration & Keys“ Zugangsdaten und eine Webhook-URL angelegt haben, werden auch Zahlungen über Links im unten beschriebenen Format gemeldet.
• Um nichts mehr anzunehmen, klicken Sie auf „Deaktivieren“, und der Link funktioniert sofort nicht mehr.

API-Integration

1. Zugangsdaten und Signatur

Händler-Dashboard → „Entwickler › Integration & Keys“ → einen merchant (UUID) und einen API key erzeugen. Es gibt je einen Satz für Live und für Test: Live nimmt echtes Geld an, Test läuft auf Testnets. Tragen Sie außerdem Ihre Website-Domains ein: url_callback, url_return und url_success müssen darauf liegen. Der API key wird nur einmal angezeigt – bewahren Sie ihn sicher und nur auf Ihrem Server auf.

Base-URL https://blockwallets.io. Jeder Endpoint ist POST + JSON, mit diesen Headern:

• merchant: Ihre merchant-UUID (sie entscheidet über Live oder Test)
• sign: md5(base64(Request-Body) + API key), wobei der Body genau der JSON-String ist, den Sie senden

Erfolg liefert {"state": 0, "result": {…}}, ein Fehler {"state": 1, "message": "…"} (siehe Fehler).

Die wichtigsten Endpoints unten haben ein Panel „Ausprobieren“: Geben Sie Ihren Test-merchant und API key ein, und die Seite signiert die Anfrage in Ihrem Browser, ruft den Endpoint auf und zeigt vollständige Anfrage und Antwort (die Zugangsdaten bleiben im Speicher der Seite). Wenn eine Signatur nicht passt, vergleichen Sie sie Schritt für Schritt mit dem Signaturprüfer.

import crypto from "node:crypto";

async function call(path, data) {
  const body = JSON.stringify(data);
  const sign = crypto.createHash("md5").update(Buffer.from(body).toString("base64") + process.env.BW_API_KEY).digest("hex");
  const res = await fetch("https://blockwallets.io" + path, {
    method: "POST",
    headers: { merchant: process.env.BW_MERCHANT, sign, "Content-Type": "application/json" },
    body,
  });
  return res.json();
}

function bw_call(string $path, array $data): array {
    $body = json_encode($data, JSON_UNESCAPED_UNICODE);
    $sign = md5(base64_encode($body) . getenv('BW_API_KEY'));
    $ch = curl_init('https://blockwallets.io' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true, CURLOPT_POSTFIELDS => $body, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['merchant: ' . getenv('BW_MERCHANT'), 'sign: ' . $sign, 'Content-Type: application/json'],
    ]);
    return json_decode(curl_exec($ch), true);
}

import base64, hashlib, json, os, requests

def bw_call(path: str, data: dict) -> dict:
    body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
    sign = hashlib.md5((base64.b64encode(body.encode()).decode() + os.environ["BW_API_KEY"]).encode()).hexdigest()
    headers = {"merchant": os.environ["BW_MERCHANT"], "sign": sign, "Content-Type": "application/json"}
    return requests.post("https://blockwallets.io" + path, data=body.encode(), headers=headers).json()

2. Rechnung erstellen POST /v1/payment

Wenn der Kunde eine Bestellung aufgibt oder auf Ihrer Aufladeseite einen Betrag eingibt, rufen Sie https://blockwallets.io/v1/payment auf und leiten ihn zur zurückgegebenen result.url weiter.

{
  "amount": "42.00",
  "currency": "USD",
  "order_id": "order_1042",
  "url_callback": "https://shop.example/webhooks/crypto",
  "url_return": "https://shop.example/cart",
  "url_success": "https://shop.example/thanks?order=1042"
}

{
  "state": 0,
  "result": {
    "uuid": "6f1c2a7e-…",
    "order_id": "order_1042",
    "amount": "42.00",
    "currency": "USD",
    "network": null,
    "address": null,
    "payer_amount": null,
    "payment_amount": null,
    "url": "https://blockwallets.io/pay/inv_01J8…",
    "expired_at": 1760965200,
    "status": "check",
    "is_final": false
  }
}

network, address und payer_amount werden gefüllt, sobald der Kunde ein Netzwerk wählt.

3. Rechnungen abfragen

• POST /v1/payment/info {"order_id": "…"} oder {"uuid": "…"}: eine Rechnung abrufen und dabei die Chain prüfen (höchstens einmal pro 10 Sekunden).
• POST /v1/payment/list: Liste, 15 pro Seite, optional date_from / date_to; nächste Seite über das zurückgegebene paginate.nextCursor (?cursor=…).
• POST /v1/payment/services: verfügbare Netzwerke und der Mindestbetrag jedes Netzwerks.
• POST /v1/payment/resend {"order_id": "…"}: den Webhook einer bezahlten / unterzahlten Rechnung erneut senden.

Webhooks sind der Hauptkanal; Abfragen sind die Reserve (zum Beispiel, wenn Ihr Server ausgefallen war und einen Webhook verpasst hat).

4. Statische Wallets POST /v1/wallet

Öffnet für einen Kunden in einem Netzwerk eine dauerhafte Adresse. Dieselbe order_id (meist Ihre Nutzer-ID) + Netzwerk ergibt immer dieselbe Adresse; alle EVM-Chains (BNB Chain, Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, X Layer) teilen sich eine Adresse, während TRON, BTC, LTC, DOGE, BCH, Solana und TON jeweils eine eigene haben. Alles, was der Kunde sendet, wird gutgeschrieben, mit einem Webhook pro Überweisung; Überweisungen in BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON werden zum Kurs des Moments, in dem sie gesehen wurden, in US-Dollar umgerechnet (payment_amount_usd).

{
  "order_id": "user_42",
  "currency": "USDT",
  "network": "tron",
  "url_callback": "https://shop.example/webhooks/crypto"
}

{
  "state": 0,
  "result": {
    "wallet_uuid": "0b9d…",
    "uuid": "5e2f…",
    "order_id": "user_42",
    "currency": "USDT",
    "network": "tron",
    "address": "TXy4…8kQ2",
    "url": "https://blockwallets.io/deposit/dac_01J8…"
  }
}

result.url ist eine gehostete Einzahlungsseite (Adresse + QR-Code + letzte Einzahlungen), die Sie dem Kunden geben können. Überweisungen unter dem Mindestbetrag des Netzwerks (meist $1, BTC $5) werden nicht automatisch gutgeschrieben; kontaktieren Sie uns, damit sie gutgeschrieben werden. Das Sperren von Adressen (/v1/wallet/block-address) wird noch nicht unterstützt.

Webhooks

Wenn sich der Status einer Rechnung ändert (paid, paid_over, wrong_amount_waiting, wrong_amount, cancel) und bei jeder Überweisung an eine statische Wallet, senden wir JSON per POST an url_callback. Eine 2xx-Antwort gilt als zugestellt; andernfalls wiederholen wir nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 12 Stunden, 24 Stunden und 24 Stunden. Sie können auch im Dashboard oder mit /v1/payment/resend erneut senden.

{
  "type": "payment",
  "uuid": "6f1c2a7e-…",
  "order_id": "order_1042",
  "amount": "42.00",
  "payment_amount": "42",
  "payment_amount_usd": "42.00",
  "merchant_amount": "41.58",
  "commission": "0.42",
  "is_final": true,
  "status": "paid",
  "from": "TQ8m…",
  "wallet_address_uuid": null,
  "network": "tron",
  "currency": "USD",
  "payer_currency": "USDT",
  "payer_amount": "42",
  "payer_amount_exchange_rate": "1",
  "additional_data": null,
  "txid": "9c1e…",
  "sign": "5f0c9b…"
}

Signatur prüfen (Pflicht)

Die Signatur ist das Feld sign im Webhook-Body: Entfernen Sie sign, kodieren Sie den Rest so neu wie PHP json_encode (kompakt, / als \/ escaped, Nicht-ASCII nicht escaped), und md5(base64(encoded) + API key) muss sign entsprechen. Verwenden Sie den API key im selben Modus. Derselbe Webhook kann mehrfach eintreffen – deduplizieren Sie über uuid + status.

Schlägt die Prüfung fehl, fügen Sie den rohen Webhook-Body in den Signaturprüfer ein: Er zeigt das Ergebnis jedes Schritts und markiert, wo Ihres abweicht (alles läuft in Ihrem Browser; der API key wird nie hochgeladen). Jeder Webhook unter „Entwickler › Webhook-Protokoll“ im Dashboard öffnet sich mit einem Klick im Prüfer.

import crypto from "node:crypto";

function verify(rawBody, apiKey) {
  const { sign, ...data } = JSON.parse(rawBody);
  const json = JSON.stringify(data).replaceAll("/", "\\/");
  const expected = crypto.createHash("md5").update(Buffer.from(json).toString("base64") + apiKey).digest("hex");
  return typeof sign === "string" && sign.length === expected.length && crypto.timingSafeEqual(Buffer.from(sign), Buffer.from(expected));
}

$data = json_decode(file_get_contents('php://input'), true);
$sign = $data['sign'] ?? '';
unset($data['sign']);
$expected = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiKey);
if (!hash_equals($expected, $sign)) {
    http_response_code(401); exit;
}

import base64, hashlib, hmac, json

def verify(raw_body: bytes, api_key: str) -> bool:
    data = json.loads(raw_body)
    sign = data.pop("sign", "")
    encoded = json.dumps(data, separators=(",", ":"), ensure_ascii=False).replace("/", "\\/")
    expected = hashlib.md5((base64.b64encode(encoded.encode()).decode() + api_key).encode()).hexdigest()
    return hmac.compare_digest(expected, sign)

Testmodus

Rechnungen, die mit dem Test-merchant und API key erstellt werden, laufen auf Testnets, ganz ohne echtes Geld. Die Zahlungsseite zeigt eine Schaltfläche „Zahlung simulieren“ (voll / halb / überzahlt), sodass Sie Statuswechsel und Webhooks sehen, ohne Testnet-Coins zu besorgen.

• POST /v1/test-webhook/payment, /v1/test-webhook/wallet: einen signierten Beispiel-Webhook an url_callback senden (übergeben Sie url_callback – Pflicht, auf einer Ihrer registrierten Website-Domains – sowie currency, network, optional status, order_id), um Ihren Prüfcode zu debuggen.
• Dashboard „Entwickler › Integration & Keys“ → „Testbenachrichtigung senden“: sendet ein Beispiel an Ihre Webhook-URL.
• Dashboard „Entwickler › Webhook-Protokoll“: jeder Zustellversuch mit Zeit, Ziel-URL, HTTP-Status, Dauer, Request-Body und der Antwort Ihres Servers (erste 4 KB); nach Bestellung oder Status filtern und mit einem Klick erneut senden. 30 Tage aufbewahrt.

Wechsel von Cryptomus

1. Dashboard „Entwickler › Integration & Keys“ → merchant und API key erzeugen.
2. Ersetzen Sie https://api.cryptomus.com in Ihrem Code durch https://blockwallets.io und verwenden Sie den neuen merchant und API key.
3. Tragen Sie Ihre Domains unter „Website-Domains“ ein (url_callback / url_return / url_success akzeptieren nur diese).

Unterstützt: /v1/payment, /v1/payment/info, /v1/payment/list, /v1/payment/services, /v1/payment/resend, /v1/wallet, /v1/test-webhook/payment, /v1/test-webhook/wallet. Unterschiede: Rechnungen werden nur in USD / USDT / USDC berechnet (alle 1:1, kein Wechselkursaufschlag); commission ist unsere Plattformgebühr (der erhaltene Betrag × der Satz des Händlers bei Erstellung der Rechnung – Standard 1%, je nach Volumen bis 0.5%; auf den Teil, den der Kunde übernimmt, wird nichts doppelt berechnet) und merchant_amount = erhalten − commission; zahlt der Kunde in BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON, nennen wir den Median mehrerer Börsen, 30 Minuten fixiert – payer_amount ist die zu sendende Coin-Menge, payer_amount_exchange_rate der USD-Wert eines Coins, und die Zahlung wird zum fixierten Kurs in payment_amount_usd umgerechnet (die Coins bleiben bei uns, es wird nichts getauscht); Netzwerke tron / bsc / eth / base / polygon / arbitrum / optimism / avalanche / xlayer / btc / ltc / doge / bch / sol / ton; Mindestlebensdauer einer Rechnung 10 Minuten; kein is_refresh und kein Sperren statischer Wallets; Webhooks kommen standardmäßig von wechselnden IPs; wenn Sie per IP freigeben, aktivieren Sie im Dashboard unter „Entwickler › Integration & Keys“ die Option „Webhooks von fester IP“, dann kommen Webhooks nur von 18.163.145.41 – eine Freigabeliste ist eine zusätzliche Schicht, prüfen Sie weiterhin sign.

Sie kommen von NOWPayments oder Coinbase Commerce? Für beide haben wir kompatible APIs – ändern Sie Base-URL und Schlüssel; siehe die Migrationsanleitung.

Netzwerke und Beträge

ERC-20-Gebühren sind hoch, daher beträgt das Minimum $5; auch die Bitcoin-Gebühren sind nicht niedrig, Minimum $5; alles andere $1. Kunden müssen im auf der Zahlungsseite gezeigten Netzwerk senden – Geld, das in einem anderen Netzwerk gesendet wird, wird nicht automatisch gutgeschrieben. BTC / LTC / DOGE / BCH zeigen „erkannt“, sobald sie im Mempool sind, und zählen, sobald sie genug Bestätigungen haben; ersetzte (RBF) oder verworfene Transaktionen zählen nicht. Native Coins (TRX, BNB, ETH, POL, AVAX, OKB, SOL, TON) werden zu einem fixierten Kurs angeboten und wie BTC / LTC / DOGE / BCH in US-Dollar gutgeschrieben; geben Sie Netzwerk und Coin an: bei Rechnungen network: "bsc", to_currency: "BNB", bei statischen Wallets network: "bsc", currency: "BNB". Ein Netzwerk allein steht standardmäßig für USDT in dieser Chain (USDC auf Base). Überweisungen von Verträgen (Multisig, Sammelauszahlungen) werden ebenfalls empfangen; bei manchen Chains ist ihr Transaktions-Hash nicht verfügbar, und txid im Webhook ist null.

Fehler

{ "state": 1, "message": "amount must be a number like 10.28" }

Ist die Signatur falsch (Invalid Sign.), enthält die Antwort ein Objekt debug: body_base64 ist das base64 des Request-Bodys, den wir empfangen haben (Ihr eigener Inhalt, niemals der API key), und body_bytes seine Länge. Vergleichen Sie es mit dem base64, das Sie signiert haben: Weichen sie ab, ist der gesendete Body nicht der signierte String (Ihr Framework hat ihn neu serialisiert, ein Proxy hat die Kodierung geändert, ein abschließender Zeilenumbruch); stimmen sie überein, ist der API key falsch. Fügen Sie es in den Signaturprüfer ein, um die erste Abweichung zu sehen.

{
  "state": 1,
  "message": "Invalid Sign.",
  "debug": {
    "body_base64": "eyJhbW91bnQiOiI0Mi4wMCIsImN1cnJlbmN5IjoiVVNEIiwi…",
    "body_bytes": 158,
    "sign_formula": "md5(body_base64 + API key)"
  }
}

FAQ

Kunden laden beliebige Beträge auf – welcher Modus?

Rechnungen. Lassen Sie den Kunden auf Ihrer Aufladeseite einen Betrag eingeben, erstellen Sie dafür eine Rechnung und schreiben Sie payment_amount_usd gut, wenn sie ankommt. Nutzen Sie statische Wallets nur, wenn Kunden eine Adresse speichern und wiederholt dorthin senden sollen.

Was, wenn ein Kunde zu wenig zahlt?

Vor Ablauf kann der Kunde die Differenz auf der Zahlungsseite nachsenden (sie zeigt, wie viel noch offen ist; Status wrong_amount_waiting, und bleiben bei der ersten Unterzahlung weniger als 30 Minuten, verschiebt sich die Frist auf 30 Minuten später). Fehlt bei Ablauf noch etwas, wird die Rechnung wrong_amount, und payment_amount_usd im Webhook ist der erhaltene Betrag; Aufladungsgeschäfte können diesen einfach gutschreiben.

Was, wenn ein Kunde zu spät oder doppelt zahlt?

Geld, das nach Ablauf eintrifft, wird trotzdem gutgeschrieben und gemeldet; Geld, das nach vollständiger Bezahlung einer Rechnung eintrifft, wird ebenfalls erfasst und ist im Dashboard sichtbar.

Was, wenn ein Kunde im falschen Netzwerk sendet?

Zum Beispiel ist die Rechnung auf TRON und er sendet von BNB Chain: Es wird nicht automatisch gutgeschrieben – kontaktieren Sie uns, dann bearbeiten wir es manuell.

Was kostet es?

1% jeder erhaltenen Zahlung, automatisch gesenkt nach dem Volumen des Vormonats (0.9% ab $50,000, 0.8% ab $100,000, 0.7% ab $250,000, 0.6% ab $500,000 und 0.5% ab $1,000,000), ohne monatliche oder Einrichtungsgebühren. Der Kunde zahlt beim Senden die Netzwerkgebühr; um die Gebühr an den Kunden weiterzugeben, setzen Sie subtract beim Erstellen einer Rechnung oder als Standard im Dashboard. Auszahlungen kosten nichts extra. Siehe Preise.

Wann kommt das Geld bei mir an?

Es wird Ihrem Guthaben gutgeschrieben, sobald die Zahlung bestätigt ist. Fordern Sie unter „Finanzen › Guthaben & Auszahlung“ eine Auszahlung auf Ihre eigene Wallet an; nach unserer Freigabe zahlen wir aus, und die On-Chain-Transaktion erscheint in Ihrem Auszahlungsverlauf.

Sie können auch die automatische Auszahlung aktivieren: Sobald Ihr verfügbares Guthaben einen von Ihnen festgelegten Betrag erreicht oder einmal täglich um 00:00 UTC, wird das gesamte verfügbare Guthaben ausgezahlt. Automatische Auszahlungen werden genauso geprüft, und jede Änderung der Einstellungen sendet eine Mitteilung an Ihre E-Mail.