---
title: Rechnungen
description: Rechnungen per API erstellen: Felder, Assets wie USDT, USDC und Bitcoin, Idempotenz, Status, Beträge, Kurs und verspätete Zahlungen bei Coinetic.
url: https://coinetic.money/de/docs/invoices/
lang: de
---

# Rechnungen

Eine Rechnung entspricht einem Kauf: Preis in Fiat oder Stablecoin, Gültigkeitsdauer und – sobald der Kunde gewählt hat – Zahlungswährung und Einzahlungsadresse.

## Erstellen

`POST /v1/invoices`

Header: `Authorization` ([CP-HMAC](https://coinetic.money/de/docs/authentication/)), `Idempotency-Key`, `Content-Type: application/json`.

`Request-Body`

```json
{
  "order_id": "ORDER-1001",
  "price_amount": "49.99",
  "price_currency": "USD",
  "allowed_assets": ["USDT-TRON", "USDC-BASE", "BTC"],
  "return_url": "https://shop.example/orders/ORDER-1001",
  "expires_in_seconds": 1800,
  "metadata": { "user_id": "42", "plan": "pro" }
}
```

| Feld | Pflicht | Regeln |
| --- | --- | --- |
| `order_id` | ja | 1–128 Zeichen, eindeutig je Händler (Wiederholung – `409 duplicate_order`) |
| `price_amount` | ja | Dezimal-**String** > 0, bis zu 18 Nachkommastellen |
| `price_currency` | ja | `USD`, `EUR`, `USDT` oder `USDC` |
| `allowed_assets` | nein | Bis zu 30 Asset-IDs (`GET /v1/assets`). Leer – alle verfügbaren. Die Rechnung erhält die **Schnittmenge** mit den verfügbaren; ist sie leer – `422 invalid_allowed_assets` |
| `return_url` | nein | `https://…` – Button „Zurück zum Shop“ |
| `expires_in_seconds` | nein | 300–86.400, Standard 1800 (30 Minuten) |
| `metadata` | nein | Bis zu 20 Schlüssel `[A-Za-z0-9_.-]{1,64}`, Werte bis 500 Zeichen; werden in der Rechnung zurückgegeben |

Antwort `201`:

```json
{
  "id": "inv_x7k2…",
  "order_id": "ORDER-1001",
  "status": "created",
  "price_amount": "49.99",
  "price_currency": "USD",
  "allowed_assets": ["USDT-TRON", "BTC"],
  "checkout_url": "https://pay.coinetic.money/pay/inv_x7k2…#t=…",
  "return_url": "https://shop.example/orders/ORDER-1001",
  "expires_at": "2026-10-12T15:30:00Z",
  "created_at": "2026-10-12T15:00:00Z",
  "quote": null,
  "paid_amount": "0", "outstanding_amount": "0", "overpaid_amount": "0",
  "refunded_amount": "0", "refundable_amount": "0",
  "payments": [],
  "metadata": { "user_id": "42", "plan": "pro" },
  "livemode": true
}
```

- `price_amount` wird in kanonischer Form ohne nachgestellte Nullen zurückgegeben: Aus `"3.00"` wird `"3"`. Vergleichen Sie Beträge als Dezimalzahlen, nicht als Float und nicht byteweise.
- `checkout_url` enthält nach dem `#` das Token der Bezahlseite. Loggen oder veröffentlichen Sie es nicht.
- `livemode: false` – eine Sandbox-Rechnung. Ein Produktiv-Shop muss solche Rechnungen ablehnen.

### Welche Assets in die Rechnung kommen

Ein Asset ist verfügbar, wenn es in Coinetic aktiviert ist, Sie ein gültiges Empfangs-Wallet für dieses Netzwerk hinterlegt und es im Dashboard nicht ausgeschlossen haben („Einstellungen“ → „Zahlungs-Assets“). Jedes Asset hat ein Minimum (`min_amount` in `GET /v1/assets`): Liegt der Rechnungsbetrag in diesem Asset darunter, wird es nicht angeboten. Beispiel: Eine Rechnung über 3 USD bei BTC = 60.000 USD entspricht 5.000 Sat bei einem Minimum von 10.000 – diese Rechnung erhält nur Stablecoins.

Das Feld `selectable_assets` enthält die Assets aus `allowed_assets`, die gerade wählbar sind; nur diese bietet die Bezahlseite an.

## Idempotenz

- `Idempotency-Key`: 8–128 druckbare ASCII-Zeichen ohne Leerzeichen, darf nicht mit `d:` beginnen. Praktisch ist ein Schlüssel aus der Bestellnummer: `order-ORDER-1001`.
- Gleicher Schlüssel, gleicher Body – **gleiche Antwort** (dieselbe Rechnung).
- Gleicher Schlüssel, anderer Body – `409 idempotency_conflict`.
- Die erste Anfrage läuft noch – `409 idempotency_in_progress`, wiederholen Sie nach einer Sekunde.
- Auch eine Ablehnung aufgrund einer Geschäftsregel (etwa `422`) wird gespeichert.

## Abrufen

`GET /v1/invoices/{id}`

Sobald der Kunde eine Währung gewählt hat, enthält die Rechnung ein `quote`:

`quote`

```json
{
  "asset_id": "USDT-TRON", "network": "tron", "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "address": "TX…", "amount_due": "49990000", "decimals": 6, "display_amount": "49.99",
  "payment_uri": "tron:…", "rate": "1", "rate_valid_until": null,
  "network_warning": "Senden Sie nur USDT im TRON-Netzwerk (TRC-20)…"
}
```

`payments` – die Zahlungen: `tx_hash`, `amount` (in kleinsten Einheiten), `confirmations`, `required_confirmations`, `state` (`mempool`, `included`, `confirmed`, `reorged`, `replaced`, `failed`, `dropped`).

`unmatched_payments` – Überweisungen an die Rechnungsadresse, die **nicht gutgeschrieben** wurden: in einem anderen EVM-Netzwerk (`wrong_network`) oder mit einem nicht freigegebenen Token (`token_not_whitelisted`). Status und `paid_amount` ändern sie nicht.

## Liste

`GET /v1/invoices?status=paid&from=…&to=…&limit=50&cursor=…`

Antwort: `{ "items": [...], "next_cursor": "…" | null }`, von neu nach alt, `limit` 1–200.

## Status

| Status | Bedeutung | Was der Shop tut |
| --- | --- | --- |
| `created` | Rechnung erstellt, keine Währung gewählt | warten |
| `awaiting_payment` | Währung gewählt, Adresse ausgegeben | warten |
| `detected` | Zahlung im Netzwerk sichtbar (Mempool) | „Zahlung erkannt“ anzeigen, **nicht ausliefern** |
| `confirming` | Im Block, weniger Bestätigungen als nötig | Fortschritt anzeigen, **nicht ausliefern** |
| `paid` | Vollständig bezahlt und bestätigt | **Bestellung ausliefern** |
| `overpaid` | Mehr als nötig bezahlt | Bestellung ausliefern; Überschuss auf Anfrage erstatten |
| `underpaid` | Weniger als nötig bestätigt (abzüglich Toleranz) | um Nachzahlung an dieselbe Adresse bitten |
| `expired` | Abgelaufen, keine Zahlung | neue Rechnung anbieten (siehe unten) |
| `late_payment` | Zahlung nach Ablauf eingegangen | Ihre Entscheidung: ausliefern oder erstatten |
| `manual_review` | Zahlung in der AML-Prüfung | Entscheidung abwarten; nicht ausliefern |
| `refunded`, `cancelled` | Abgeschlossen | nicht ausliefern |

> **Die wichtigste Regel.** Liefern Sie nur bei `paid` oder `overpaid` aus, abgefragt über `GET /v1/invoices/{id}`.

### Stablecoin-Zahlung nach Ablauf

USDT oder USDC für eine Rechnung in USD tragen kein Kursrisiko, daher wird eine Zahlung nach Ablauf (bis zu 30 Tage) automatisch gutgeschrieben: Eine Rechnung, die bereits `invoice.expired` erhalten hat, wird `paid`, und es kommt `invoice.paid` mit `data.late: true`. Schließen Sie eine Bestellung bei `invoice.expired` daher **nicht endgültig**. Bei volatilen Assets führt eine solche Zahlung zu `late_payment`.

## Beträge und Kurs

- Der Preis wird in der Rechnungswährung angegeben. Den Krypto-Betrag fixiert Coinetic in dem Moment, in dem der Kunde die Währung wählt.
- **Stablecoin in seiner eigenen Währung** (USDT für eine Rechnung in USD): 1:1, der Betrag gilt bis zum Ende der Rechnung.
- **Volatiles Asset** (BTC, ETH u. a.): Median der Kurse von Kraken, Coinbase und Bitstamp, fixiert für 20 Minuten.
- `amount_due` – in kleinsten Einheiten des Assets (USDT auf TRON hat 6 Stellen: `"49990000"` = 49,99). `display_amount` – derselbe Wert in üblicher Schreibweise.
- Die Unterzahlungstoleranz (standardmäßig 0,5 %) deckt Rundungen der Wallets ab.

Den Referenzkurs liefert `GET /v1/rates?base=BTC&quote=USD`. Zeigen Sie dem Kunden auf dieser Basis keinen „exakten“ Krypto-Betrag an: Verbindlich ist nur der Betrag aus der Rechnung.