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

Header: Authorization (CP-HMAC), Idempotency-Key, Content-Type: application/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" }
}

Antwort 201:

{
  "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

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

{
  "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

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

Status

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.