Erste Schritte als Entwickler · TgPay Crypto API

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

Öffne Mehr → Händler-API und wähle App erstellen.
Gib unter App-Name einen Namen ein (z. B. „Mein Shop“) und optional eine Webhook-URL (optional).
Akzeptiere die Bedingungen im Formular und tippe auf App erstellen. Bestätige bei Aufforderung mit PIN oder Biometrie. Mit dem Erstellen einer App akzeptierst du die Bedingungen der Händler-API – wofür du die API nutzen darfst und wofür nicht.
Kopiere den API-Token sofort. Er wird einmal angezeigt und nie wieder – die App speichert nur seinen Hash.
Sende deine erste Anfrage mit dem Token im Header TgPayCrypto-API-Token.

Der Bildschirm Händler-API: Erstelle eine App, um einen API-Token zu erhalten

Dein erster Aufruf

Richte deinen Client auf die API-Basis https://app.tgpaycrypto.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. Schreibende Methoden wie createInvoice, transfer, createCheck, deleteInvoice und deleteCheck erlauben nur POST. Parameter kannst du als JSON-Body, form-urlencoded oder als Query-Parameter senden. Verwende vorzugsweise einen Request-Body, damit Beträge und Idempotenzschlüssel nicht in URL-Zugriffsprotokollen landen.

Testnet

Entwickle deine Integration zuerst im Testnet – dieselbe API, dieselbe Mini App, Test-Coins ohne Wert:

	Mainnet	Testnet
Bot	@tgpaycryptobot	@tgpaycrypto_testnet_bot
API-Basis	`https://app.tgpaycrypto.com/pay/api`	`https://testnet.tgpaycrypto.com/pay/api`
MCP-Server	`https://app.tgpaycrypto.com/mcp`	`https://testnet.tgpaycrypto.com/mcp`

Apps und Token sind getrennt: Ein Testnet-Token funktioniert nicht im Mainnet und umgekehrt. Öffne für Testguthaben die Mini App des Testnets und tippe auf dem Startbildschirm auf Test-Coins holen. Du erhältst ein Testpaket als gewöhnliche Einzahlungen; Assets auf deaktivierten Netzwerken werden übersprungen. Die App zeigt, was gutgeschrieben wurde und wann eine weitere Anfrage möglich ist. Ein zweites Telegram-Konto kann als Kunde deine Testrechnungen bezahlen.

Einzahlungen und Auszahlungen werden ohne echte Blockchain-Transaktionen simuliert. Sende niemals echtes Guthaben an eine Testnet-Einzahlungsadresse. Die API-Spezifikation ist dieselbe; verfügbare Funktionen, Kurse und Limits können aber vom Mainnet abweichen. Bist du fertig, erstelle eine App für den Produktivbetrieb in @tgpaycryptobot und wechsle die Basis-URL.

Eine App verwalten

Öffne eine App in der Händler-API, um ihre App-ID und ihr Guthaben zu sehen. Dort kannst du:

Die Webhook-URL setzen oder ändern – unter Webhook – und speichern.
Zusätzliche Webhook-Events wählen – über die Schalter Zusätzliche Webhook-Events im Bereich Webhook wählst du Ereignistypen jenseits von invoice_paid aus (siehe die Webhook-Referenz).
Einschränken, wen die API bezahlen darf – unter Auszahlungseinstellungen steht Auszahlungen über die API bei einer neuen App auf Jeder Nutzer; stelle auf Nur Nutzer aus der Liste um (und trage die Empfänger ein) oder auf Aus, wenn deine Integration nie jemanden bezahlt – eine Absicherung für den Fall, dass der Token nach außen gelangt (siehe Auszahlungsmodus).
Eingeschränkte Token erstellen – öffne Zugriff und Tokens. Unter Eingeschränkte Token kannst du zusätzliche API-Token mit ausgewählten Berechtigungen erstellen (siehe die API-Referenz).
Token erneuern – unter Zugriff und Tokens. Dadurch erhältst du einen neuen Token, und der alte wird 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 – zahle zuerst das verfügbare Guthaben aus; sonst wird das Löschen mit app_has_balance abgelehnt. Kläre vor dem Löschen auch offene Schecks und ausstehende Auszahlungen. Die App verschwindet aus der Liste und ihre Token funktionieren nicht mehr. Der Zahlungsverlauf bleibt erhalten.

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 TgPayCrypto-API-Signature (mit TgCryptoPay-API-Signature und Crypto-Pay-API-Signature als Kompatibilitäts-Alias): HMAC-SHA256 über den rohen Body, mit dem SHA-256 deines Haupt-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 braucht bei eingerichteter Webhook-URL keine separate Aktivierung. 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 das Verhalten bei Wiederholungen stehen in der Webhook-Referenz.

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

Er autorisiert Auszahlungen 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 mit ausschließlich der Berechtigung invoices kann Rechnungen erstellen und löschen, aber keine Überweisungen ausführen, Schecks erstellen oder Rückerstattungen auslösen.