Erste Schritte als Entwickler

Erstelle eine App in der Mini App, kopiere ihren API-Token einmalig und beginne, die API aufzurufen. Die gesamte Einrichtung liegt unter Mehr → Händler-API.

Schritte

1. Öffne Mehr → Händler-API.
2. Gib einen App-Namen ein (z. B. „Mein Shop“) und optional eine Webhook-URL.
3. Tippe auf App erstellen.
4. Kopiere den API-Token sofort. Er wird einmal angezeigt und nie wieder – die App speichert nur seinen Hash.
5. Sende deine erste Anfrage mit dem Token im Header TgCryptoPay-API-Token.

Dein erster Aufruf

Richte deinen Client auf die API-Basis https://crypto.tgpaybot.com/pay/api und rufe getMe auf, um zu prüfen, ob der Token funktioniert. getBalance liefert die Guthaben deiner App, getCurrencies die Assets, die du verwenden kannst.

Lesende Methoden sind GET. Die Methoden, die Geld bewegen – createInvoice, transfer, createCheck und ihre Gegenstücke zum Löschen –, sind bewusst nur POST: Beträge und Idempotenzschlüssel gehören nicht in Zugriffsprotokolle. Parameter kannst du als JSON-Body, form-urlencoded oder als Query-Parameter senden.

Eine App verwalten

Jede App-Karte in der Händler-API zeigt ihre App-ID und ihr Guthaben und erlaubt dir:

• Die Webhook-URL setzen oder ändern und speichern.
• Zusätzliche Webhook-Events wählen – sobald eine Webhook-URL gesetzt ist, kannst du über die Schalter unter Zusätzliche Webhook-Events Ereignistypen jenseits von invoice_paid aktivieren (siehe die Webhook-Referenz).
• Eingeschränkte Token erstellen – zusätzliche API-Token unter Eingeschränkte Token, jeder begrenzt auf die Berechtigungen, die du auswählst (siehe die API-Referenz).
• Token erneuern – stellt einen neuen Token aus und macht den alten sofort ungültig. Nutze das, wenn ein Token nach außen gelangt ist; der neue wird einmal angezeigt, genau wie bei der Erstellung.
• Löschen – die App authentifiziert sich nicht mehr, ihr Guthaben und ihr Zahlungsverlauf bleiben aber erhalten. Eine App zu löschen lässt ihr Geld nie verschwinden.

Webhooks

Wenn du eine Webhook-URL setzt, sendet die App per POST einen signierten JSON-Body dorthin:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

Die Signatur steht im Header TgCryptoPay-API-Signature (mit Crypto-Pay-API-Signature als Kompatibilitäts-Alias): HMAC-SHA256 über den rohen Body, mit dem SHA-256 deines API-Tokens als Schlüssel. Prüfe sie, bevor du irgendeinem Inhalt im Payload vertraust.

Zustellungen werden über einen längeren Zeitraum mit exponentiell wachsenden Abständen wiederholt, und update_id bleibt über alle Wiederholungen gleich – nutze es als Schlüssel für deine Deduplizierung und mache deinen Handler idempotent.

invoice_paid wird immer zugestellt. Andere Ereignistypen – abgelaufene Rechnungen, eingelöste Schecks, Rückerstattungen, Abo-Ereignisse – aktivierst du über die Schalter Zusätzliche Webhook-Events. Die vollständige Liste, die Formate der Payloads und der Zeitplan der Wiederholungen stehen in der Webhook-Referenz.

⚠️ Schütze den Token wie einen privaten Schlüssel

Er autorisiert Ausschüttungen aus deinem App-Guthaben. Bewahre ihn auf deinem Server auf, nie in einer mobilen App, in einem Frontend-Bundle oder in einer eingecheckten Konfiguration. Wenn du dir nicht sicher bist, ob er nach außen gelangt ist, erneuere ihn – die Erneuerung wirkt sofort und kostet nichts. Und gib jedem Server nur, was er braucht: Ein eingeschränkter Token ohne die Berechtigung payouts kann Rechnungen erstellen, dein Guthaben aber nie abziehen.