# blockwallets Cryptomus-kompatible API

> Die Cryptomus-kompatible API von blockwallets: Rechnungen und statische Wallets, Signierung, Webhooks und Prüfung, Testmodus, Netzwerke, Fehler und der Wechsel von Cryptomus durch Ändern der Domain.
>
> HTML: https://blockwallets.io/docs/cryptomus?lang=de · English: https://blockwallets.io/docs/cryptomus.md?lang=en

## 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**.

Empfohlen · für die meisten Integrationen**Rechnungen**
Der Kunde wählt auf Ihrer Seite ein Produkt oder gibt einen Betrag ein, Sie erstellen eine Rechnung, und er sendet den auf der Zahlungsseite angezeigten Betrag. Jede Rechnung hat eine neue Adresse und einen Countdown; kommt das Geld an, benachrichtigen wir Sie mit dem tatsächlich erhaltenen Betrag.

`POST /v1/payment` → Webhook `type: payment`

Optional**Statische Wallets**
Kein Betrag im Voraus: Jeder Kunde bekommt pro Netzwerk eine dauerhafte Adresse, die er in seiner Wallet speichert und jederzeit nutzt. Jede Überweisung löst einen eigenen Webhook aus.

`POST /v1/wallet` → Webhook `type: wallet`

Im Zweifel nehmen Sie Rechnungen. Ohne Code sind die [Zahlungslinks](https://blockwallets.io/docs/cryptomus?lang=de#links) im Dashboard Rechnungen, die für Sie erstellt werden. Noch kein Händler? Beantragen Sie den Zugang auf der [Startseite](https://blockwallets.io/?lang=de#join); nach der Freigabe melden Sie sich im [Händler-Dashboard](https://blockwallets.io/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:

- 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.

- 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.

- 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).

- 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`.

- Das Geld wird Ihrem Guthaben gutgeschrieben; zahlen Sie es im Händler-Dashboard auf Ihre eigene Wallet aus.

#### Rechnungsstatus

| status | Bedeutung | Was Sie tun |
| --- | --- | --- |
| `check` | Wartet auf Zahlung | — |
| `confirm_check` | Überweisung gesehen, wartet auf Bestätigungen | — |
| `wrong_amount_waiting` | Erhalten, aber zu wenig; der Kunde kann an dieselbe Adresse nachzahlen (wenn `is_payment_multiple` true ist; einmal benachrichtigt) | — (nach der Nachzahlung erhalten Sie `paid`) |
| `paid` | Bezahlt | Versenden / gutschreiben nach `payment_amount_usd` |
| `paid_over` | Bezahlt und überzahlt | Dasselbe (`payment_amount_usd` ist der erhaltene Betrag) |
| `wrong_amount` | Mit weniger als dem vollen Betrag abgelaufen (bei `is_payment_multiple` false: die erste zu geringe Überweisung) | Aufladungsgeschäfte können den erhaltenen `payment_amount_usd` gutschreiben; Shops bitten den Kunden, den Rest zu zahlen |
| `cancel` | Abgelaufen, ohne dass etwas eingegangen ist | — (später eingehendes Geld wird trotzdem gutgeschrieben und gemeldet) |

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](https://blockwallets.io/docs/cryptomus?lang=de#errors)).

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](https://blockwallets.io/docs/sign?lang=de).

```nodejs
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();
}
```

```php
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);
}
```

```python
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.

```json
{
  "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"
}
```

| Parameter | Pflicht | Beschreibung |
| --- | --- | --- |
| `amount` | Ja | Betrag als String mit bis zu zwei Nachkommastellen: `"42.00"`. Ihr Preis oder eine vom Kunden eingegebene Zahl; nicht unter dem Mindestbetrag des gewählten Netzwerks (siehe [Netzwerke](https://blockwallets.io/docs/cryptomus?lang=de#networks)) |
| `currency` | Ja | `USD`, `USDT` oder `USDC`, alle 1:1 |
| `order_id` | Ja | Ihre Bestellnummer: Buchstaben, Ziffern, `-`, `_`, ≤ 100 Zeichen. Ein erneuter Aufruf mit derselben order_id liefert die bestehende Rechnung (keine doppelten Bestellungen) |
| `url_callback` | Nein | Webhook-URL. Ohne sie wird kein Webhook gesendet |
| `url_return` | Nein | Wohin „Zurück“ vor der Zahlung führt |
| `url_success` | Nein | Wohin der Kunde nach der Zahlung geht |
| `network` | Nein | Ein Netzwerk vorauswählen: `tron` / `bsc` / `eth` / `base` / `polygon` / `arbitrum` / `optimism` / `avalanche` / `xlayer` / `btc` / `ltc` / `doge` / `bch` / `sol` / `ton`; weglassen, damit der Kunde auf der Zahlungsseite wählt |
| `to_currency` | Nein | Coin in diesem Netzwerk: `USDT` / `USDC`; bei `btc` / `ltc` / `doge` / `bch` ist es `BTC` / `LTC` / `DOGE` / `BCH` (optional) |
| `lifetime` | Nein | Lebensdauer der Rechnung in Sekunden, 300 – 43200, Standard 3600; alles unter 600 zählt als 600 |
| `accuracy_payment_percent` | Nein | Wie viel Unterzahlung noch als bezahlt gilt, 0 – 5, Standard 0. `100` = alles akzeptieren, was ankommt: `paid` sobald bestätigt (`paid_over` bei mehr), im Webhook nach `payment_amount_usd` gutschreiben – gut für Aufladungen. Wenn weggelassen, gilt im Dashboard die „Betragsregel“ unter „Einstellungen › Zahlungsregeln & Gebühren“: „Gutschreiben, was ankommt“ bedeutet 100 |
| `subtract` | Nein | Anteil der Plattformgebühr, den der Kunde zahlt, 0 – 100, zu `payer_amount` addiert (die Plattformgebühr beträgt 1%, bei höherem Volumen weniger; bei 1% kostet eine Rechnung über $100 den Kunden mit 100 genau $101.00; siehe [Preise](https://blockwallets.io/pricing?lang=de)). Wenn weggelassen, gilt im Dashboard die Einstellung „Gebühren und Unterzahlung“ unter „Einstellungen › Zahlungsregeln & Gebühren“ (Standard 0) |
| `is_payment_multiple` | Nein | Ob eine Unterzahlung nachgezahlt werden kann, Standard true: Status `wrong_amount_waiting`, zahlt der Kunde den Rest an dieselbe Adresse, wird es `paid` (bleiben bei der ersten Unterzahlung weniger als 30 Minuten, verschiebt sich die Frist auf 30 Minuten später). false: Die erste zu geringe Überweisung ergibt `wrong_amount`. Wenn weggelassen, gilt die Dashboard-Einstellung |
| `additional_data` | Nein | Ein beliebiger String (≤ 255), der in Abfragen und Webhooks unverändert zurückgegeben wird |

```json
{
  "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`).

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

```json
{
  "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.

```json
{
  "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…"
}
```

| type | Wann | Gutschrift |
| --- | --- | --- |
| `payment` | Der Status einer Rechnung hat sich geändert – siehe `status` | `payment_amount_usd` bei `paid` / `paid_over` gutschreiben; über `uuid` deduplizieren |
| `wallet` | Eine Überweisung ist bei einer statischen Wallet eingegangen (`status` ist immer `paid`; `order_id` ist die, mit der Sie die Wallet geöffnet haben) | `payment_amount_usd` gutschreiben; jede Überweisung hat eine eigene `uuid` – darüber deduplizieren |

#### 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](https://blockwallets.io/docs/sign?lang=de) 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.

```nodejs
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));
}
```

```php
$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;
}
```

```python
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

- Dashboard „Entwickler › Integration & Keys“ → merchant und API key erzeugen.

- Ersetzen Sie `https://api.cryptomus.com` in Ihrem Code durch `https://blockwallets.io` und verwenden Sie den neuen merchant und API key.

- 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](https://blockwallets.io/docs/migrate?lang=de).

### Netzwerke und Beträge

| Coin | Netzwerk | network-Parameter | Minimum | Eingang |
| --- | --- | --- | --- | --- |
| USDT | TRON | `tron` | $1 | ~1 Min. |
| USDT | BNB Chain | `bsc` | $1 | ~1 Min. |
| USDC | BNB Chain | `bsc` | $1 | ~1 Min. |
| USDT | Ethereum | `eth` | $5 | ~1 Min. |
| USDC | Ethereum | `eth` | $5 | ~1 Min. |
| USDC | Base | `base` | $1 | ~1 Min. |
| USDT | Polygon | `polygon` | $1 | ~1 Min. |
| USDC | Polygon | `polygon` | $1 | ~1 Min. |
| USDT | Arbitrum | `arbitrum` | $1 | ~1 Min. |
| USDC | Arbitrum | `arbitrum` | $1 | ~1 Min. |
| USDT | Optimism | `optimism` | $1 | ~1 Min. |
| USDC | Optimism | `optimism` | $1 | ~1 Min. |
| USDT | Avalanche | `avalanche` | $1 | ~1 Min. |
| USDC | Avalanche | `avalanche` | $1 | ~1 Min. |
| USDT | X Layer | `xlayer` | $1 | ~1 Min. |
| USDC | X Layer | `xlayer` | $1 | ~1 Min. |
| USD1 | BNB Chain | `bsc` | $1 | ~1 Min. |
| FDUSD | BNB Chain | `bsc` | $1 | ~1 Min. |
| DAI | Ethereum | `eth` | $5 | ~1 Min. |
| DAI | Arbitrum | `arbitrum` | $1 | ~1 Min. |
| DAI | Base | `base` | $1 | ~1 Min. |
| BTC | Bitcoin | `btc` | $5 | ~10 Min. |
| LTC | Litecoin | `ltc` | $1 | ~3 Min. |
| DOGE | Dogecoin | `doge` | $1 | ~1 Min. |
| BCH | Bitcoin Cash | `bch` | $1 | ~10 Min. |
| TRX | TRON | `tron` | $1 | ~1 Min. |
| BNB | BNB Chain | `bsc` | $1 | ~1 Min. |
| ETH | Ethereum | `eth` | $5 | ~1 Min. |
| ETH | Base | `base` | $1 | ~1 Min. |
| ETH | Arbitrum | `arbitrum` | $1 | ~1 Min. |
| ETH | Optimism | `optimism` | $1 | ~1 Min. |
| POL | Polygon | `polygon` | $1 | ~1 Min. |
| AVAX | Avalanche | `avalanche` | $1 | ~1 Min. |
| OKB | X Layer | `xlayer` | $1 | ~1 Min. |
| USDT | Solana | `sol` | $1 | ~1 Min. |
| USDC | Solana | `sol` | $1 | ~1 Min. |
| SOL | Solana | `sol` | $1 | ~1 Min. |
| USDT | TON | `ton` | $1 | ~1 Min. |
| TON | TON | `ton` | $1 | ~1 Min. |

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

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

| HTTP | Häufige Ursachen |
| --- | --- |
| 422 | Fehlende oder fehlerhafte Parameter; Betrag unter dem Netzwerk-Minimum; Callback- / Weiterleitungs-URL nicht auf Ihren registrierten Domains; nicht unterstützter Coin / nicht unterstütztes Netzwerk bei `/v1/payment` |
| 401 | Falscher merchant, falsches `sign` (`Invalid Sign.`) oder ein rotierter API key |
| 404 | Die Rechnung existiert nicht oder gehört Ihnen nicht (`Payment not found`); bei `/v1/wallet` nicht unterstützte Kombination aus Coin und Netzwerk (`The service was not found`) |
| 503 | Das Netzwerk ist vorübergehend nicht verfügbar – wählen Sie ein anderes oder wählen Sie keines vor |

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](https://blockwallets.io/docs/sign?lang=de) ein, um die erste Abweichung zu sehen.

```json
{
  "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](https://blockwallets.io/pricing?lang=de).

#### 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.