Händler-API-Referenz

Die Konventionen, die alle Methoden teilen, plus die Katalogmethoden nur zum Lesen. Seiten Methode für Methode: Rechnungen und Rückerstattungen, Überweisungen und Schecks, Abos, Webhooks.

Die API ist Crypto-Bot-kompatibel: Eine bestehende Crypto-Bot-Integration funktioniert, nachdem du nur die Basis-URL und den Token geändert hast. Alles, was über diesen Vertrag hinausgeht, ist unten als Erweiterung markiert.

Eine maschinenlesbare OpenAPI-3.1-Spezifikation der gesamten API – jede Methode, jedes Objekt, jeder Fehlername und jeder Webhook – wird zusammen mit diesen Seiten veröffentlicht: crypto-pay-openapi.yaml · crypto-pay-openapi.json. Gib sie Codegeneratoren, API-Clients oder deinen KI-Werkzeugen.

Basis-URL und Authentifizierung

Alle Methoden liegen unter https://crypto.tgpaybot.com/pay/api/<methodName>.

Authentifiziere jede Anfrage mit dem Token im Header TgCryptoPay-API-Token (Crypto-Pay-API-Token wird als Kompatibilitäts-Alias akzeptiert; werden beide gesendet, gewinnt der kanonische). Ein fehlender, ungültiger oder widerrufener Token – oder der Token einer gelöschten App – liefert 401 unauthorized.

Der Token hat die Form <app_id>:<secret> und wird einmal angezeigt, bei der Erstellung oder Erneuerung; der Server speichert nur seinen Hash. Siehe Erste Schritte als Entwickler.

Token und Berechtigungen

Zwei Arten von Zugangsdaten authentifizieren sich identisch:

• Der Haupt-Token – voller Zugriff auf jede Methode und der einzige Schlüssel, der Webhooks signiert.
• Eingeschränkte Token (Erweiterung) – bis zu 10 gleichzeitig pro App, erstellt unter Mehr → Händler-API im Bereich Eingeschränkte Token, jeder mit einer Bezeichnung und einer Teilmenge der Berechtigungen. Einen davon zu widerrufen wirkt sofort und berührt die anderen nicht; den Haupt-Token zu erneuern berührt sie ebenfalls nicht.

Berechtigung	Methoden, die sie freischaltet
(jeder gültige Token)	getMe, getCurrencies, getExchangeRates
read	getBalance, getStats, getInvoices, getChecks, getTransfers, getSubscriptionPlans, getSubscriptions
invoices	createInvoice, deleteInvoice
refunds	refundInvoice
payouts	transfer, transferBatch
checks	createCheck, deleteCheck
subscriptions	createSubscriptionPlan, archiveSubscriptionPlan, cancelSubscription

Berechtigungen sind additiv und unabhängig – invoices schließt read nicht ein, ein Server, der nur Rechnungen erstellt, kann also einen Token halten, der nichts lesen kann. Eine Methode aufzurufen, die der Token nicht abdeckt, liefert 403 scope_required. getMe meldet die scopes des aktuellen Tokens (null beim Haupt-Token) und token_name, du kannst also jederzeit prüfen, was du in der Hand hast.

Anfragen und Antworten

• Lesende Methoden sind GET mit Parametern im Query-String. Geldbewegende Methoden sind ausschließlich POST – Parameter als JSON-Body, form-urlencoded oder als Query-Parameter (bei einem Konflikt gewinnt der Body); multipart/form-data wird abgelehnt.
• Jede Antwort ist JSON mit derselben Hülle: Erfolg {"ok": true, "result": …}, Fehler {"ok": false, "error": {"code": <HTTP status>, "name": "<error_name>"}}. Verzweige auf error.name – das ist der stabile, maschinenlesbare String.
• Ein Sonderfall: Ein Query-Wert mit falschem Typ bei einer GET-Methode (z. B. offset=abc) liefert HTTP 422 mit einem {"detail": …}-Body außerhalb der Hülle. Sende typrichtige Query-Werte.

Beträge

• Krypto-Beträge sind Dezimalstrings in ganzen Coin-Einheiten ("10.5") – nie JSON-Zahlen. Antworten führen außerdem amount_minor (Erweiterung): den ganzzahligen Wert in kleinsten Einheiten als String, weil Ganzzahlen in Wei-Größenordnung eine JavaScript-Number überlaufen lassen.
• Die decimals pro Asset kommen aus getCurrencies – steuere deine Betragsrechnung damit, statt sie fest einzuprogrammieren.
• Fiat-Beträge haben höchstens 2 Nachkommastellen.
• Kurse sind Festkomma-Strings, nie Zahlen.

Paginierung

Listenmethoden (getInvoices, getChecks, getTransfers, getSubscriptions) nehmen offset (Standard 0) und count (Standard 100, max. 1000; getSubscriptions max. 500) und liefern {"items": […]}, neueste zuerst. Die ID-Filter (invoice_ids, check_ids, transfer_ids) sind kommagetrennte Listen von Ganzzahlen. Zeitstempel sind überall ISO-8601-Strings.

Idempotenz: spend_id

Methoden, die Geld bewegen, nehmen einen vom Aufrufer erzeugten Schlüssel spend_id (1–64 Zeichen): Pflicht bei transfer und bei jedem Element von transferBatch, optional bei createCheck und refundInvoice (Erweiterung – nutze ihn trotzdem). Eine Wiederholung mit demselben Schlüssel und denselben Parametern gibt das ursprüngliche Ergebnis wieder, statt zweimal Guthaben zu bewegen; eine Anfrage nach einem Timeout kannst du also immer gefahrlos wiederholen. Derselbe Schlüssel mit anderen Parametern liefert 409 idempotency_conflict; eine Wiederholung, während die ursprüngliche noch läuft, liefert 409 idempotency_in_progress.

Anfragelimits

Pro App, geteilt über alle ihre Token; eine Überschreitung liefert 429 rate_limited:

Methode	Limit
createInvoice, createCheck	60 pro Minute
refundInvoice, transfer	30 pro Minute
transferBatch	10 pro Minute

Lesende Methoden sind nicht begrenzt. Während einer Plattformwartung liefern schreibende Methoden 503 maintenance, während Lesezugriffe weiter funktionieren.

Katalog- und Kontomethoden

getMe

GET /pay/api/getMe – keine Parameter. Liefert die Identität der App: app_id, name, payment_processing_bot_username, webhook_url, webhook_events (die zusätzlichen Webhook-Typen, die die App aktiviert hat) und die oben beschriebenen Introspektionsfelder des Tokens scopes / token_name.

getBalance

GET /pay/api/getBalance – keine Parameter. Liefert ein Array mit einer Zeile pro unterstütztem Asset, auch bei null: currency_code, available (verfügbares Guthaben), onhold (Guthaben, das in deinen offenen Schecks einbehalten wird) und amount_minor.

getCurrencies

GET /pay/api/getCurrencies – keine Parameter. Die maßgebliche Liste dessen, was die API unterstützt: Krypto-Zeilen (is_blockchain: true) und die Fiat-Währungen, in denen Rechnungen ausgepreist werden können (is_fiat: true). Jede Zeile führt code, name, decimals und das Flag is_stablecoin.

getExchangeRates

GET /pay/api/getExchangeRates – keine Parameter. Kurse von Krypto zu Fiat: source, target, rate (ein Festkomma-String) und is_valid – false bedeutet, dass die gesamte Tabelle aus einem veralteten Cache stammt; behandle diese Kurse dann nur als Richtwerte.

getStats

GET /pay/api/getStats – optional start_at / end_at (ISO 8601; das Standardfenster sind die letzten 24 Stunden). Liefert volume (USD-Wert der bezahlten Rechnungen im Fenster), conversion (bezahlt/erstellt, in Prozent), unique_users_count, created_invoice_count, paid_invoice_count und die tatsächlichen Grenzen des Fensters. Ein nicht lesbares Datum liefert 400 invalid_date.

Fehler, die jede Methode liefern kann

HTTP	error.name	Wann
401	unauthorized	fehlender, ungültiger oder widerrufener Token
403	scope_required	dem Token fehlt die Berechtigung der Methode
400	invalid_request	nicht lesbare oder ungültige Parameter (POST)
429	rate_limited	Anfragelimit überschritten
503	maintenance	Plattformwartung (schreibende Methoden)
500	internal_error	unerwarteter Serverfehler

Methodenspezifische Fehler stehen auf der Seite der jeweiligen Methode.